feat: hot-swap upgrade — replace the binary while every tab stays live

Add src/hotswap.rs: on 'tab-atelier upgrade' / POST /upgrade the running
process re-execs the binary installed at its own path, handing each
tab's PTY master fd (CLOEXEC cleared) plus a pid-validated JSON manifest
across the exec. Because exec keeps the pid, tab shells remain our
children — process groups, controlling TTYs, cgroups, and nftables
rules are untouched, so agents and builds inside the tabs never notice.

The new image adopts the fds at boot (AdoptedPty mirrors alacritty's
Unix Pty: same poller tokens, SIGCHLD pipe, waitpid exit detection)
instead of forking shells; grid contents restore through the existing
saved-output replay and the carried raw ring bytes re-seed viewer
scrollback. PTY readers freeze during the handoff so unread bytes wait
in the kernel and are parsed by the new binary — nothing is lost.

Adopted tabs skip exactly the work that assumes a fresh shell: agent
auto-resume (would double-launch the still-running claude), the GUI
net-off bubblewrap respawn (still jailed), the headless nftables
teardown/re-apply (would blip enforcement; only the gating DNS resolver
is respawned), the cgroup stale reap, and the agent reaper's provenance
record (removed at swap so the new boot can't SIGKILL the inherited
fleet). A shell that dies mid-swap falls back to a normal fresh fork;
a failed exec rolls back fully and the old binary keeps running.

Trigger surface: POST /upgrade (master token, 409 when no binary at the
re-exec path, 501 on Windows), 'upgrade' subcommand on both binaries,
docs/hot-swap.md, openapi.yaml entry.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LTkVxFVGsaywyG4iJyTyvc

Author: claude

AGENTS.md

@@ -17,6 +17,7 @@ Tab Atelier is a Guake-style drop-down terminal emulator for Linux (X11), built
 - `src/power.rs` — per-tab power/energy monitoring via wattaouille
 - `src/screenshot.rs` — X11 screenshot capture to BMP
 - `src/schedule.rs` — per-tab off-hours auto-lock (OSM `opening_hours` + IANA tz). See `docs/schedule.md`.
+- `src/hotswap.rs` — in-place binary upgrade keeping every tab's shell alive (exec + PTY-fd handoff). See `docs/hot-swap.md`.
 - `src/tracking.rs` — Wakatime integration
 - `src/platform/linux.rs` — Linux-specific platform code (XDG dirs, X11 hotkeys, process info)
 

Cargo.lock

@@ -222,6 +222,15 @@ tempfile = "3"
 # platform::random_bytes() has a real CSPRNG. Already present
 # transitively (rand, uuid) — gated to Windows so the Linux dep graph
 # is untouched.
+# Hot-swap upgrade (src/hotswap.rs): safe wrappers for the fd handoff —
+# fcntl CLOEXEC twiddling, waitpid/kill on the adopted PTY children,
+# TIOCSWINSZ on the inherited masters. Both crates are already in the
+# tree transitively (alacritty_terminal / polling), so these direct
+# deps add no new compilation units.
+[target.'cfg(unix)'.dependencies]
+rustix = { version = "1", features = ["fs", "process", "termios"] }
+signal-hook = "0.3"
+
 # gpui with the X11 backend — Linux desktop build only.
 [target.'cfg(target_os = "linux")'.dependencies]
 gpui = { version = "0.2", default-features = false, features = ["x11"], optional = true }

Cargo.toml

@@ -97,6 +97,7 @@ The `.deb` lays out the following under FHS-standard paths:
 - Tabs, working directories, and full terminal output persisted across restarts
 - Active tab selection restored on startup
 - **Agent auto-resume**: tabs that were running `catbus-agent` or `claude` at last save reopen with `catbus-agent --resume <uuid>` / `claude --resume <uuid>` typed into the freshly-spawned shell
+- **Hot-swap upgrade**: `tab-atelier upgrade` re-execs the newly installed binary in place, handing every tab's live PTY across — shells (and the agents running in them) are never restarted. See [docs/hot-swap.md](docs/hot-swap.md)
 
 **Preferences**
 - Theme selection (Dark, Tomorrow Night Blue)
@@ -226,6 +227,7 @@ Selected routes:
 | `DELETE` | `/tabs/{idx}` | Close a tab |
 | `POST` | `/tabs/rotate-tokens` | Revoke all per-tab share tokens (share links 401) — master only |
 | `POST` | `/master-token/reset` | Hot-swap the master API token (old token 401s) — master only |
+| `POST` | `/upgrade` | Hot-swap onto the newly installed binary, tabs stay live ([docs](docs/hot-swap.md)) — master only |
 
 Bind addresses for both listeners are configurable in preferences (`api_addr`, `api_tls_addr`); pass `--read-only` to launch a second instance that serves the API but refuses every mutating verb.
 

README.md

@@ -25,6 +25,8 @@ tags:
     description: Tab list, I/O and per-tab state
   - name: tokens
     description: Master token + share-link token management
+  - name: admin
+    description: Process-level administration (hot-swap upgrade)
 paths:
   /tabs:
     get:
@@ -295,6 +297,33 @@ paths:
               schema: { type: object, properties: { token: { type: string } } }
         "401": { $ref: "#/components/responses/Unauthorized" }
         "500": { description: Could not persist token }
+  /upgrade:
+    post:
+      tags: [admin]
+      summary: Hot-swap onto the newly installed binary (tabs stay live)
+      description: >
+        Re-exec the running process onto the binary currently installed at
+        its own path, handing every tab's live PTY across the exec — the
+        shells, and whatever runs inside them, are never restarted. Install
+        the new binary first (apt upgrade / copy over the file), then call
+        this. The swap happens moments after the response flushes; expect
+        the API to drop briefly while the new binary boots and re-binds.
+        Unix only; master token only.
+      security:
+        - bearerAuth: []
+      responses:
+        "200":
+          description: Swap armed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  upgrading: { type: boolean }
+                  pid: { type: integer }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "409": { description: No binary found at the re-exec path }
+        "501": { description: Platform without exec-based handoff (Windows) }
 components:
   securitySchemes:
     bearerAuth:

assets/openapi.yaml

@@ -0,0 +1,97 @@
+# Hot swap — upgrade without losing a single tab
+
+`tab-atelier upgrade` (or `POST /upgrade`) replaces the **running**
+binary with the one currently installed at its path while every tab's
+shell — and whatever is running inside it (a `claude` session, a build,
+an ssh connection) — keeps running, unaware anything happened.
+
+## Using it
+
+```sh
+# 1. Install the new version over the old one (any of these):
+sudo apt install ./tab-atelier_0.6.0_amd64.deb
+sudo cp target/release/tab-atelier /usr/bin/tab-atelier
+
+# 2. Ask the running instance to swap itself:
+tab-atelier upgrade                 # desktop GUI
+tab-atelier-headless upgrade        # headless daemon
+# or: curl -X POST http://127.0.0.1:7890/upgrade \
+#          -H "Authorization: Bearer $(tab-atelier token)"
+```
+
+The process re-execs within a couple of seconds (its next owner-loop
+tick). The GUI window closes and reopens on the new version; the
+headless daemon's API drops for a moment and re-binds. Tabs, shells,
+agents, cgroups, and nftables egress rules all survive.
+
+## How it works
+
+A normal restart forks fresh shells and replays saved output text. The
+hot swap instead `exec()`s the new binary **in place** (`src/hotswap.rs`):
+
+1. **Freeze.** `PtyTap::read` starts reporting `WouldBlock`, parking
+   every PTY reader. Bytes the shells emit from now on wait in the
+   kernel PTY buffers and are read by the new binary — nothing is lost.
+2. **Flush.** The usual quit-path persistence runs (tabs.json, per-tab
+   output/uptime/energy), so the new binary restores names, cwds, grid
+   contents, and scrollback through the existing restore code.
+3. **Handoff manifest.** For each live tab, a dup of the PTY **master**
+   fd gets its `CLOEXEC` flag cleared, the raw `PtyRing` bytes are
+   written to a sidecar (so web-viewer scrollback survives), and
+   `(tab id, fd number, shell pid)` is recorded in
+   `<state>/tab-atelier/handoff.json`.
+4. **exec.** The process replaces itself with the binary at its own
+   path (`/proc/self/exe`, with dpkg's ` (deleted)` suffix stripped),
+   passing `--handoff <manifest>` on argv. Because `exec` keeps the
+   pid, the tab shells remain our **children** — process groups,
+   controlling TTYs, and SIGCHLD reaping are all untouched. If the exec
+   fails, everything rolls back and the old binary keeps running.
+5. **Adopt.** At boot the new binary validates the manifest (schema
+   version + writer pid must equal its own pid — after exec they match;
+   a stale manifest from a crashed swap never can) and stashes the fds
+   in a registry keyed by tab id. The tab restore path claims entries
+   from that registry and wraps each fd in an `AdoptedPty` — a drop-in
+   for alacritty's Unix `Pty` (same poller tokens, SIGCHLD pipe, and
+   `waitpid`-based exit detection) — instead of forking a shell.
+   Unclaimed fds are closed once every tab has spawned.
+
+## What deliberately does NOT happen for adopted tabs
+
+- **No agent auto-resume.** The agent is still running in the adopted
+  shell; typing `claude --resume …` would double-launch the session.
+- **No net-off respawn (GUI).** The adopted shell is still inside the
+  bubblewrap netns the previous run put it in.
+- **No nftables teardown/re-apply (headless).** The tab's table and
+  cgroup are kernel state that survived the exec; re-applying would
+  open a brief unconfined window for the running shell. Only the
+  daemon-side gating DNS resolver (a thread that died with the old
+  process) is respawned for domain-allowlist tabs.
+- **No orphan reaping.** The swap deletes the agent reaper's provenance
+  record (clean-handover semantics) and the headless cgroup reaper
+  skips adopted tabs — both would otherwise SIGKILL exactly the
+  processes the handoff kept alive.
+
+## Failure behaviour
+
+- Shell died mid-swap → its manifest entry fails the `waitpid` probe
+  and the tab falls back to a normal fresh fork (with the carried ring
+  bytes still seeding the scrollback above it).
+- `exec` failed (binary missing/corrupt) → `CLOEXEC` is restored, the
+  manifest is removed, readers unfreeze, and the old binary keeps
+  running; the error lands in the log and the endpoint caller's next
+  poll.
+- Downgrading to a pre-hot-swap binary → the old binary ignores
+  `--handoff`, so tabs respawn fresh (a normal restart) and the handed
+  fds leak until the shells are HUP'd. Upgrade forward instead.
+
+## Limits
+
+- Unix only (Windows ConPTY handles can't cross an exec; the endpoint
+  answers 501 there).
+- WebSocket viewers and `remote attach` clients are disconnected by the
+  exec and must reconnect — their scrollback survives via the carried
+  ring bytes.
+- The single-instance lock is dropped and re-acquired across the exec
+  (std opens it `CLOEXEC`); a different instance racing for it in that
+  window loses the tabs to the "already running" check — in practice
+  unobservable.

docs/hot-swap.md

@@ -2777,6 +2777,36 @@ fn handle_connection<S: Read + Write>(stream: &mut S, state: &Arc<Mutex<TabSnaps
             drop(state);
             respond_json(stream, 200, &format!(r#"{{"revoked":{revoked}}}"#));
         }
+        ("POST", "/upgrade") => {
+            // Hot-swap upgrade: re-exec the (freshly installed) binary at
+            // our own install path while every tab's live PTY is handed
+            // across the exec — the shells, and whatever runs in them,
+            // never notice (see src/hotswap.rs). Master token only (not
+            // in the share-token allowlist); refused in read-only mode by
+            // the is_mutating gate above. The swap happens on the owner
+            // loop's next tick, after this response has flushed — expect
+            // the API to drop for a moment while the new binary boots and
+            // re-binds.
+            #[cfg(unix)]
+            {
+                if !crate::hotswap::reexec_target_ok() {
+                    error_json(
+                        stream,
+                        409,
+                        "re-exec target missing — install the new binary at this binary's path first",
+                    );
+                    return;
+                }
+                crate::hotswap::request_upgrade();
+                respond_json(
+                    stream,
+                    200,
+                    &format!(r#"{{"upgrading":true,"pid":{}}}"#, std::process::id()),
+                );
+            }
+            #[cfg(not(unix))]
+            error_json(stream, 501, "hot swap is not supported on this platform");
+        }
         ("POST", "/master-token/reset") => {
             // Hot-swap the master API token: generate a fresh one, persist
             // it to api.token (so `tab-atelier token` and saved configs

src/api.rs

@@ -769,17 +769,32 @@ impl AppState {
                 // airgapped. Skipped (net left on) when bwrap isn't
                 // installed, so a persisted net-off tab doesn't boot
                 // into a dead shell on a host without bubblewrap.
+                // A hot-swap-adopted shell is skipped too: it is still
+                // inside the bubblewrap netns the previous run put it
+                // in, and respawning would kill exactly the process the
+                // handoff kept alive. (Net-off tabs never defer their
+                // spawn, so `was_adopted` is already accurate here.)
                 if ts.net_disabled && crate::bwrap_available() {
                     view.update(cx, |v, _| {
                         v.set_net_disabled(true);
-                        v.respawn(cwd.as_deref());
+                        if !v.was_adopted() {
+                            v.respawn(cwd.as_deref());
+                        }
                     });
                 }
                 // Auto-resume: if this tab had an agent session and kind
                 // persisted, queue the resume command to be typed into the
                 // freshly-spawned shell — UNLESS we already launched the
                 // agent directly above (then typing it would double-launch).
-                let pending_agent_resume = if agent_launch.is_some() || crate::read_only() {
+                // …and never into a hot-swap-adopted shell: its agent is
+                // still running, so typing a `--resume` would double-
+                // launch the session. `adoptable` covers deferred tabs
+                // whose adoption happens later in the boot loader.
+                let pending_agent_resume = if agent_launch.is_some()
+                    || crate::read_only()
+                    || crate::hotswap::adoptable(&ts.id)
+                    || view.read(cx).was_adopted()
+                {
                     None
                 } else {
                     match (&ts.agent_kind, &ts.agent_session_id) {
@@ -995,6 +1010,12 @@ impl AppState {
                     })
                     .unwrap_or(true);
                 if done {
+                    // Every tab has spawned (and claimed its hot-swap
+                    // handoff, if any). A handoff fd still unclaimed
+                    // belongs to a tab that no longer exists — close it
+                    // so its orphaned shell gets its HUP instead of
+                    // wedging on a full PTY buffer nobody drains.
+                    crate::hotswap::close_unclaimed();
                     break;
                 }
             }
@@ -1984,6 +2005,16 @@ impl AppState {
             return;
         }
 
+        // A hot-swap upgrade came in (`POST /upgrade`): flush all state,
+        // then replace this process with the (re)installed binary at our
+        // own path, handing every tab's live PTY across the exec — the
+        // shells never notice. Returns only if the exec failed.
+        #[cfg(unix)]
+        if crate::hotswap::upgrade_requested() && !crate::read_only() {
+            self.hot_swap(cx);
+            return;
+        }
+
         // Skipped entirely while nobody consumes the API — the previous
         // snapshot stays in place (never wiped with an empty one) and
         // the first request after idle serves it, at most 2 s + idle
@@ -2430,7 +2461,11 @@ impl AppState {
         self.tabs[idx].name = new_name;
     }
 
-    fn close_all_tabs(&mut self, cx: &mut Context<Self>) {
+    /// Unconditional flush of tabs.json + every tab's output / uptime /
+    /// energy files — the "this process is about to go away" save.
+    /// Shared by `close_all_tabs` (quit) and `hot_swap` (exec into the
+    /// next binary).
+    fn flush_all_state(&mut self, cx: &mut Context<Self>) {
         let state_base = platform::state_base_dir();
         // Snapshot cwd from /proc one last time before child processes
         // disappear; fall back to the cached last_known_cwd otherwise.
@@ -2492,6 +2527,47 @@ impl AppState {
                 tab.energy_wh_last_saved = tab.energy_wh;
             }
         }
+    }
+
+    /// Replace this process with the binary at our own install path,
+    /// handing every live tab's PTY across the exec (see
+    /// [`crate::hotswap`]). The window closes and reopens; the shells —
+    /// and whatever is running in them — never notice. Returns only if
+    /// the exec failed, in which case we keep running as before.
+    #[cfg(unix)]
+    fn hot_swap(&mut self, cx: &mut Context<Self>) {
+        crate::hotswap::clear_upgrade_request();
+        self.flush_all_state(cx);
+        let mut sources = Vec::new();
+        for tab in &self.tabs {
+            let view = tab.view.read(cx);
+            // Skeletons (no shell yet) and exited shells carry no fd —
+            // they restore from tabs.json exactly like today.
+            if view.has_exited() {
+                continue;
+            }
+            let Some(master) = view.handoff_master() else {
+                continue;
+            };
+            let ring_arc = view.pty_ring();
+            let ring = ring_arc
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .since(0);
+            sources.push(crate::hotswap::HandoffSource {
+                id: tab.id.clone(),
+                master,
+                pid: view.pid(),
+                ring,
+            });
+        }
+        log::info!("hot swap: handing off {} live tab(s)", sources.len());
+        let err = crate::hotswap::exec_swap(&sources);
+        log::error!("hot swap failed, continuing on the old binary: {err}");
+    }
+
+    fn close_all_tabs(&mut self, cx: &mut Context<Self>) {
+        self.flush_all_state(cx);
 
         if let Some(ref tracker) = self.tracker {
             tracker.shutdown();
@@ -5339,6 +5415,16 @@ pub fn run() {
 
     info!("starting Tab Atelier v{}", env!("CARGO_PKG_VERSION"));
 
+    // Hot-swap handoff: when the previous binary exec'd into us it left
+    // `--handoff <manifest>` on argv, naming the live PTY fds it kept
+    // open across the exec. Adopt them BEFORE the reaper and the tab
+    // restore below, so restored tabs reattach to their running shells
+    // instead of forking fresh ones.
+    let adopted = crate::hotswap::adopt_from_args();
+    if adopted > 0 {
+        info!("hot swap: inherited {adopted} live tab(s) from the previous binary");
+    }
+
     // Reap agent processes leaked by a prior (unclean) run before we
     // restore any tab — reclaims the stopped `claude` ghosts that
     // reparented to init. Provenance-based (only kills processes this GUI