Persist sessions across server restarts via tmux

Each session is now backed by a tmux session named webshell-<uuid>:

- new Session() spawns `tmux new-session -A -s webshell-<id> <shell>`,
  so restarting the dev server reattaches to the same long-lived tmux
  session instead of killing the shell.
- SessionManager.rehydrate() runs on boot: lists tmux sessions with
  our prefix, captures each pane's full scrollback via
  `capture-pane -p -e -J -S -`, and seeds it as the initial history
  frame. First client connect after a restart replays everything that
  happened before the crash.
- Session title persists as tmux option `@title`; rename pushes it
  into tmux so it survives restarts too.
- Session.kill() now also calls `tmux kill-session` so destroy
  actually destroys the backing shell.
- configureTmux() turns off the status bar per session.
- Dockerfile adds the tmux package.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chapterjason

.devcontainer/Dockerfile

@@ -8,7 +8,7 @@ RUN apt-get update \
     && apt-get install -y --no-install-recommends \
         sudo ca-certificates git openssh-client \
         curl jq less vim bash-completion locales unzip \
-        build-essential python3 \
+        build-essential python3 tmux \
     && rm -rf /var/lib/apt/lists/* \
     && sed -i 's/^# *\(en_US.UTF-8\)/\1/' /etc/locale.gen \
     && locale-gen \

server/src/index.ts

@@ -12,6 +12,7 @@ import { mountWsRouter } from "./ws/router.js";
 process.env["PORT"] = String(PORT);
 
 const manager = new SessionManager();
+await manager.rehydrate();
 const server = http.createServer();
 mountWsRouter(server, manager);
 

server/src/session/manager.ts

@@ -3,10 +3,34 @@ import type { CreateSessionRequest, SessionInfo } from "../types/session.js";
 import { log } from "../utils/log.js";
 import { defaultCwd, defaultShell } from "../utils/shell.js";
 import { Session } from "./session.js";
+import * as tmux from "./tmux.js";
 
 export class SessionManager {
   private readonly sessions = new Map<string, Session>();
 
+  async rehydrate(): Promise<void> {
+    const existing = await tmux.listSessions();
+    for (const t of existing) {
+      const initialHistory = await tmux.capturePane(t.name);
+      const session = new Session({
+        id: t.id,
+        createdAt: t.createdAt,
+        title: t.title,
+        shell: defaultShell(),
+        cwd: defaultCwd(),
+        cols: DEFAULT_COLS,
+        rows: DEFAULT_ROWS,
+        initialHistory,
+      });
+      this.sessions.set(session.id, session);
+      log("session", "rehydrate", session.id, session.title);
+      session.onExit((code, signal) => {
+        log("session", "removed after exit", session.id, "code=", code, "signal=", signal);
+        this.sessions.delete(session.id);
+      });
+    }
+  }
+
   create(req: CreateSessionRequest): Session {
     const session = new Session({
       title: req.title ?? `shell-${this.sessions.size + 1}`,

server/src/session/session.ts

@@ -3,21 +3,25 @@ import { randomUUID } from "node:crypto";
 import { SCROLLBACK_BYTES } from "../config.js";
 import type { SessionInfo } from "../types/session.js";
 import { Scrollback } from "./scrollback.js";
+import * as tmux from "./tmux.js";
 
 export type OutputListener = (chunk: string) => void;
 export type ExitListener = (code: number, signal?: number) => void;
 
 export interface SessionOptions {
+  readonly id?: string;
+  readonly createdAt?: number;
   readonly title: string;
   readonly shell: string;
   readonly cwd: string;
   readonly cols: number;
   readonly rows: number;
+  readonly initialHistory?: string;
 }
 
 export class Session {
-  readonly id: string = randomUUID();
-  readonly createdAt: number = Date.now();
+  readonly id: string;
+  readonly createdAt: number;
   readonly shell: string;
 
   private _title: string;
@@ -27,20 +31,40 @@ export class Session {
   private readonly scrollback = new Scrollback(SCROLLBACK_BYTES);
   private readonly outputListeners = new Set<OutputListener>();
   private readonly exitListeners = new Set<ExitListener>();
+  private readonly tmuxName: string;
 
   constructor(opts: SessionOptions) {
+    this.id = opts.id ?? randomUUID();
+    this.createdAt = opts.createdAt ?? Date.now();
     this._title = opts.title;
     this.shell = opts.shell;
     this._cols = opts.cols;
     this._rows = opts.rows;
-
-    this.pty = spawn(opts.shell, [], {
-      name: "xterm-256color",
-      cols: opts.cols,
-      rows: opts.rows,
-      cwd: opts.cwd,
-      env: process.env as Record<string, string>,
-    });
+    this.tmuxName = tmux.sessionName(this.id);
+
+    if (opts.initialHistory) this.scrollback.append(opts.initialHistory);
+
+    this.pty = spawn(
+      "tmux",
+      [
+        "new-session",
+        "-A",
+        "-s",
+        this.tmuxName,
+        "-x",
+        String(opts.cols),
+        "-y",
+        String(opts.rows),
+        opts.shell,
+      ],
+      {
+        name: "xterm-256color",
+        cols: opts.cols,
+        rows: opts.rows,
+        cwd: opts.cwd,
+        env: process.env as Record<string, string>,
+      },
+    );
 
     this.pty.onData((data) => {
       this.scrollback.append(data);
@@ -50,6 +74,14 @@ export class Session {
     this.pty.onExit(({ exitCode, signal }) => {
       for (const listener of this.exitListeners) listener(exitCode, signal);
     });
+
+    void this.configureTmux();
+  }
+
+  private async configureTmux(): Promise<void> {
+    await tmux.setOption(this.tmuxName, "status", "off");
+    await tmux.setOption(this.tmuxName, "history-limit", "10000");
+    await tmux.setTitle(this.tmuxName, this._title);
   }
 
   get title(): string {
@@ -58,6 +90,7 @@ export class Session {
 
   setTitle(title: string): void {
     this._title = title;
+    void tmux.setTitle(this.tmuxName, title);
   }
 
   get cols(): number {
@@ -106,6 +139,7 @@ export class Session {
     } catch {
       // already dead
     }
+    void tmux.kill(this.tmuxName);
   }
 
   info(): SessionInfo {

server/src/session/tmux.ts

@@ -0,0 +1,86 @@
+import { spawn } from "node:child_process";
+
+const SESSION_PREFIX = "webshell-";
+
+export function sessionName(id: string): string {
+  return `${SESSION_PREFIX}${id}`;
+}
+
+export function idFromName(name: string): string {
+  return name.slice(SESSION_PREFIX.length);
+}
+
+export function isOurs(name: string): boolean {
+  return name.startsWith(SESSION_PREFIX);
+}
+
+export interface TmuxSession {
+  readonly name: string;
+  readonly id: string;
+  readonly title: string;
+  readonly createdAt: number;
+}
+
+function run(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const p = spawn("tmux", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    p.stdout.on("data", (d) => (stdout += d));
+    p.stderr.on("data", (d) => (stderr += d));
+    p.on("close", (code) => {
+      if (code === 0) resolve(stdout);
+      else reject(new Error(`tmux ${args.join(" ")} exited ${code}: ${stderr.trim()}`));
+    });
+    p.on("error", reject);
+  });
+}
+
+export async function listSessions(): Promise<TmuxSession[]> {
+  try {
+    const out = await run([
+      "list-sessions",
+      "-F",
+      "#{session_name}\t#{session_created}\t#{@title}",
+    ]);
+    return out
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => {
+        const parts = line.split("\t");
+        const name = parts[0] ?? "";
+        const created = parts[1] ?? "0";
+        const rawTitle = parts[2] ?? "";
+        const title = rawTitle.length > 0 ? rawTitle : name;
+        return {
+          name,
+          id: idFromName(name),
+          title,
+          createdAt: Number(created) * 1000,
+        };
+      })
+      .filter((s) => isOurs(s.name));
+  } catch {
+    return [];
+  }
+}
+
+export async function capturePane(name: string): Promise<string> {
+  try {
+    return await run(["capture-pane", "-p", "-e", "-J", "-S", "-", "-t", name]);
+  } catch {
+    return "";
+  }
+}
+
+export async function setTitle(name: string, title: string): Promise<void> {
+  await run(["set-option", "-t", name, "@title", title]).catch(() => {});
+}
+
+export async function setOption(name: string, option: string, value: string): Promise<void> {
+  await run(["set-option", "-t", name, option, value]).catch(() => {});
+}
+
+export async function kill(name: string): Promise<void> {
+  await run(["kill-session", "-t", name]).catch(() => {});
+}