AWS terminals survive the app closing (tmux) and reattach on connect #87

Merged
jknapp merged 6 commits from feat/aws-persistent-sessions into main 2026-11-17 23:46:53 +00:00
Owner

AWS terminals (Fargate and EC2) now survive the app closing or losing its connection, so a Claude Code session — remote control included — keeps working with the app closed. Docker projects are unchanged.

How

  • Image: tmux plus /etc/triple-c/tmux.conf (status bar off, no prefix key, truecolor, output kept in xterm.js's own scrollback, last screen kept when a session exits).
  • One tmux server per tab (tmux -L triple-c-<key> … new-session -A), so each tab's credentials stay in its own exec environment and never go on argv. Keys are validated as [A-Za-z0-9-]{1,64} everywhere.
  • Detach vs end: closing a tab ends its session. App exit, a dropped tunnel or a re-attach only detach (the agent's SIGHUP reaches the tmux client, the server lives on). A tab closed while disconnected is ended at the next connect.
  • Reattach: after a restart or reconnect the app reopens its tabs with their history, and never re-runs the launch command (claude update runs once). Sessions from the web terminal or another machine appear in Project Home → Sessions with Reattach / End. A detached Claude is flagged as "keeps the workspace running".
  • Stop and the TERM hook end every tmux server, and wait for their pane processes, before the WIP push. The lifetime-cap push does the same.
  • Fallback: an image without tmux runs terminals the old way and shows a one-time notice.
  • Web terminal execs are keyed web-<key>, so desktop and web never take over each other's exec. The web terminal's Close ends only sessions that connection opened.

Cost note

A Claude session left running keeps the workspace up after the app closes, until it ends, the user stops the workspace, or the lifetime cap is hit. This is the point of the feature; it is stated in HostSection's notes and CLAUDE.md.

Testing

  • cargo test --locked 1,653 passed · vitest 1,418 passed · tsc clean.
  • Local Docker: Claude Code's TUI renders inside tmux. An ignored live test through the real agent checks that a session survives its client going away, keeps its own environment, replays its history and reattaches.
  • Not yet run on AWS. That needs the tmux image, which :edge gets when this merges. The checks to run there are in the PR's follow-up (restart and reattach, Stop with Push, idle stop, two machines).

🤖 Generated with Claude Code

AWS terminals (Fargate and EC2) now survive the app closing or losing its connection, so a Claude Code session — remote control included — keeps working with the app closed. Docker projects are unchanged. ## How - **Image:** `tmux` plus `/etc/triple-c/tmux.conf` (status bar off, no prefix key, truecolor, output kept in xterm.js's own scrollback, last screen kept when a session exits). - **One tmux server per tab** (`tmux -L triple-c-<key> … new-session -A`), so each tab's credentials stay in its own exec environment and never go on argv. Keys are validated as `[A-Za-z0-9-]{1,64}` everywhere. - **Detach vs end:** closing a tab ends its session. App exit, a dropped tunnel or a re-attach only detach (the agent's SIGHUP reaches the tmux client, the server lives on). A tab closed while disconnected is ended at the next connect. - **Reattach:** after a restart or reconnect the app reopens its tabs with their history, and never re-runs the launch command (`claude update` runs once). Sessions from the web terminal or another machine appear in Project Home → Sessions with Reattach / End. A detached Claude is flagged as "keeps the workspace running". - **Stop and the TERM hook** end every tmux server, and wait for their pane processes, before the WIP push. The lifetime-cap push does the same. - **Fallback:** an image without tmux runs terminals the old way and shows a one-time notice. - **Web terminal** execs are keyed `web-<key>`, so desktop and web never take over each other's exec. The web terminal's Close ends only sessions that connection opened. ## Cost note A Claude session left running keeps the workspace up after the app closes, until it ends, the user stops the workspace, or the lifetime cap is hit. This is the point of the feature; it is stated in HostSection's notes and CLAUDE.md. ## Testing - `cargo test --locked` 1,653 passed · vitest 1,418 passed · tsc clean. - Local Docker: Claude Code's TUI renders inside tmux. An ignored live test through the real agent checks that a session survives its client going away, keeps its own environment, replays its history and reattaches. - **Not yet run on AWS.** That needs the tmux image, which `:edge` gets when this merges. The checks to run there are in the PR's follow-up (restart and reattach, Stop with Push, idle stop, two machines). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
jknapp added 6 commits 2026-11-17 23:10:08 +00:00
tmux rides the Python apt layer (the last, cheapest one) and
/etc/triple-c/tmux.conf (outside the seed-only home) makes it invisible
behind xterm.js: no prefix, no status line, escape-time 0, truecolor,
OSC 8/52, and smcup@/rmcup@/indn@ so output lands in xterm.js's own
scrollback (xterm.js's CSI S drops lines instead of keeping them).

The entrypoint's TERM hook ends the app's tmux servers before its own
WIP push, so nothing writes after the push's snapshot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On an AWS project whose image has tmux and /etc/triple-c/tmux.conf, each
tab (Claude and bash, desktop and web terminal) runs its unchanged
command inside its own tmux server, tmux -L triple-c-<session id>, so the
server inherits only that exec's environment (copy-at-connect pairs stay
off argv). App exit, a dropped tunnel and the agent's SIGHUP only detach;
closing a tab ends the session (kill-server).

- host/persistent.rs: command construction, probe cached per tunnel
  (forgotten when a tunnel registers), list/history/end/end_all, replay.
- storage/terminal_store.rs: per-project open terminals (id = tmux key,
  kind, label) in terminal-sessions.json; pruned by the workspace listing,
  cleared on Stop and Remove.
- New commands list_workspace_terminals, reattach_terminal_session
  (attach-session, never creates; optional history replay),
  end_workspace_terminal; open_terminal_session returns
  {persistent, notice} (one-time no-tmux notice).
- Stop ends every tmux server in the step that closes the terminals,
  before the WIP push's snapshot.
- ExecSessionManager: an exec that takes a session id over ends the old
  one without its exit callback.
- Ignored live test through the real agent (host::persistent::live_tests).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tmux sends terminfo's clear when its client exits; without an alternate
screen that wiped Claude's or the shell's last output from the tab.
clear=\E[H keeps it. Checked by feeding tmux's real output into xterm.js:
bash clear, ED 2, a curses alternate screen, a re-attach over an old
screen and Claude Code's TUI all match tmux's own view of the pane, and
300 fast lines all reach the scrollback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A tab on a persistent terminal reattaches when its connection drops
  (retrying while the tunnel comes back, "[Session ended]" only when the
  workspace says it is gone, or the project stopped); closing a tab ends it.
- usePersistentTerminals: once per AWS connection (project id + endpoint)
  the terminals this app opened that still run are reopened as tabs, in
  order, without taking focus; a reopened tab attaches only after its
  listeners are up, so its replayed history and tmux's first draw land.
- Project Home -> Sessions lists the workspace's terminals (open here,
  detached, attached elsewhere, opened elsewhere) with Reattach and End.
- The one-time "no tmux in this image" notice is a toast.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fix(aws): persistent terminals review fixes
Secret Scan / scan (push) Successful in 7s
Build App (Preview) / compute-version (pull_request) Successful in 12s
Secret Scan / scan (pull_request) Successful in 10s
Build App (Preview) / create-release (pull_request) Successful in 2s
Build App (Preview) / build-macos (pull_request) Successful in 6m50s
Build Container / build-container (pull_request) Successful in 7m27s
Build App (Preview) / build-windows (pull_request) Successful in 15m59s
Build App (Preview) / build-linux (pull_request) Successful in 23m19s
Build App (Preview) / prune-previews (pull_request) Successful in 3s
Build App (Preview) / test (pull_request) Successful in 26m19s
ac0bb456d3
- Probe is three-state: an unanswered probe is an Err (tab retries), never
  "no tmux" — nothing is pruned or ended on it, opens fail rather than
  silently losing persistence.
- Web terminal execs are web-<key>: a desktop reattach no longer
  supersedes the web exec, nor does a web close/disconnect touch the
  desktop's.
- A tab closed while disconnected is queued (pending_end) and ended at
  the next connect; a reattach of a closed/queued id is Ended and is not
  remembered again.
- Cost ruling documented: a detached Claude keeps the workspace up
  (HostSection note, Sessions flags detached Claude sessions).
- end_all waits for pane pids; the same script runs in the entrypoint's
  TERM hook and before the idle watcher's lifetime-cap push.
- TMUX/TMUX_TMPDIR dropped from the client env and reserved.
- Store cleared on a move to Docker and on a death-watch stop.
- Frontend: no duplicate reopen of a tab still opening; quick-exit
  backoff then stop; the replay is exactly one chunk, so live output
  keeps its URL/OSC/SSO handling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jknapp merged commit a0afa5ce20 into main 2026-11-17 23:46:53 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: CyberCoveLLC/Triple-C#87