refactor: 移除独立 hub/proxy/executor/gateway crate，统一为 gateway tunnel 架构

- 删除 aether-hub、aether-proxy 独立项目及其 Dockerfile/配置
- 删除 crates/aether-executor 和 crates/aether-gateway 全部模块
- 新增 apps/ 目录作为应用入口
- 将 hub 概念重构为 gateway tunnel transport
- 将 executor 重构为 execution runtime
- 新增 tunnel.rs 合约定义和 testkit tunnel/execution_runtime 模块
- 更新 Python 服务层和测试适配新架构命名

apps/aether-proxy/src/setup/mod.rs

@@ -0,0 +1,5 @@
+pub(crate) mod service;
+mod tui;
+pub(crate) mod upgrade;
+
+pub use self::tui::{run, SetupOutcome};

apps/aether-proxy/src/setup/service.rs

@@ -0,0 +1,256 @@
+//! Systemd service installation for aether-proxy.
+//!
+//! Called from the setup TUI when the user enables "Install Service".
+//! The unit file points to the binary and config at their current
+//! absolute paths -- no files are copied.
+
+use std::path::Path;
+use std::process::Command;
+
+const UNIT_PATH: &str = "/etc/systemd/system/aether-proxy.service";
+const SERVICE_NAME: &str = "aether-proxy";
+
+/// Whether systemd service installation is possible (systemd present + root).
+pub fn is_available() -> bool {
+    is_systemd_available() && is_root()
+}
+
+/// Install aether-proxy as a systemd service.  Must be run as root.
+pub fn install_service(config_path: &Path) -> anyhow::Result<()> {
+    if !is_systemd_available() {
+        anyhow::bail!("systemd not available");
+    }
+    if !is_root() {
+        anyhow::bail!("root required, use: sudo ./aether-proxy setup");
+    }
+
+    let exe_path = std::env::current_exe()?.canonicalize()?;
+    let exe_str = exe_path
+        .to_str()
+        .ok_or_else(|| anyhow::anyhow!("binary path contains invalid UTF-8"))?;
+
+    let config_abs = std::fs::canonicalize(config_path)?;
+    let config_str = config_abs
+        .to_str()
+        .ok_or_else(|| anyhow::anyhow!("config path contains invalid UTF-8"))?;
+
+    let working_dir = config_abs
+        .parent()
+        .unwrap_or_else(|| Path::new("/"))
+        .to_str()
+        .unwrap_or("/");
+
+    // Stop existing service if running (ignore errors)
+    if Path::new(UNIT_PATH).exists() {
+        eprintln!("  Stopping existing service...");
+        let _ = Command::new("systemctl")
+            .args(["stop", SERVICE_NAME])
+            .status();
+    }
+
+    // Write unit file
+    eprintln!("  Generating systemd unit file...");
+    eprintln!("    Binary:  {}", exe_str);
+    eprintln!("    Config:  {}", config_str);
+    eprintln!("    WorkDir: {}", working_dir);
+
+    let unit_content = format!(
+        "[Unit]\n\
+         Description=Aether Proxy\n\
+         After=network.target\n\
+         \n\
+         [Service]\n\
+         Type=simple\n\
+         WorkingDirectory={working_dir}\n\
+         Environment=AETHER_PROXY_CONFIG={config_str}\n\
+         ExecStart={exe_str}\n\
+         Restart=on-failure\n\
+         RestartSec=5\n\
+         LimitNOFILE=65535\n\
+         UMask=0077\n\
+         \n\
+         [Install]\n\
+         WantedBy=multi-user.target\n",
+    );
+    std::fs::write(UNIT_PATH, &unit_content)?;
+
+    // Reload and enable
+    eprintln!("  Enabling and starting service...");
+    run_cmd("systemctl", &["daemon-reload"])?;
+    run_cmd("systemctl", &["enable", "--now", SERVICE_NAME])?;
+
+    // Verify
+    eprintln!();
+    let output = Command::new("systemctl")
+        .args(["is-active", SERVICE_NAME])
+        .output()?;
+    let state = String::from_utf8_lossy(&output.stdout).trim().to_string();
+
+    if state == "active" {
+        eprintln!("  Service started successfully!");
+    } else {
+        eprintln!("  Service state: {} (check logs)", state);
+    }
+
+    eprintln!();
+    eprintln!("  Commands:");
+    eprintln!("    ./aether-proxy status          # service status");
+    eprintln!("    ./aether-proxy logs            # tail logs");
+    eprintln!("    sudo ./aether-proxy restart    # restart");
+    eprintln!("    sudo ./aether-proxy stop       # stop");
+    eprintln!("    sudo ./aether-proxy uninstall  # remove service");
+    eprintln!();
+
+    Ok(())
+}
+
+fn is_systemd_available() -> bool {
+    Command::new("systemctl")
+        .arg("--version")
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+pub(crate) fn is_root() -> bool {
+    #[cfg(unix)]
+    {
+        unsafe { libc::geteuid() == 0 }
+    }
+    #[cfg(not(unix))]
+    {
+        false
+    }
+}
+
+/// Whether a systemd unit file is currently installed.
+pub fn is_installed() -> bool {
+    Path::new(UNIT_PATH).exists()
+}
+
+/// Remove the systemd service (called from setup TUI when Install Service is toggled off).
+pub fn uninstall_service() -> anyhow::Result<()> {
+    if !Path::new(UNIT_PATH).exists() {
+        return Ok(());
+    }
+
+    eprintln!("  Stopping and removing existing service...");
+    let _ = Command::new("systemctl")
+        .args(["disable", "--now", SERVICE_NAME])
+        .status();
+
+    std::fs::remove_file(UNIT_PATH)?;
+    eprintln!("  Removed {}", UNIT_PATH);
+    run_cmd("systemctl", &["daemon-reload"])?;
+    eprintln!("  Service uninstalled.");
+    eprintln!();
+
+    Ok(())
+}
+
+/// Check if the systemd service is currently active.
+pub fn is_service_active() -> bool {
+    std::path::Path::new(UNIT_PATH).exists()
+        && Command::new("systemctl")
+            .args(["is-active", "--quiet", SERVICE_NAME])
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+            .map(|s| s.success())
+            .unwrap_or(false)
+}
+
+// ── CLI subcommands (systemd wrappers) ──────────────────────────────────────
+
+fn ensure_service_installed() -> anyhow::Result<()> {
+    if !std::path::Path::new(UNIT_PATH).exists() {
+        anyhow::bail!("service not installed, run `sudo ./aether-proxy setup` first");
+    }
+    Ok(())
+}
+
+fn ensure_root_and_service() -> anyhow::Result<()> {
+    ensure_service_installed()?;
+    if !is_root() {
+        anyhow::bail!("root required, use: sudo ./aether-proxy <command>");
+    }
+    Ok(())
+}
+
+/// `aether-proxy status` -- show service status.
+pub fn cmd_status() -> anyhow::Result<()> {
+    ensure_service_installed()?;
+    let status = Command::new("systemctl")
+        .args(["status", SERVICE_NAME])
+        .status()?;
+    // systemctl status returns non-zero when inactive; that's fine
+    std::process::exit(status.code().unwrap_or(1));
+}
+
+/// `aether-proxy logs` -- tail service logs.
+pub fn cmd_logs() -> anyhow::Result<()> {
+    ensure_service_installed()?;
+    let status = Command::new("journalctl")
+        .args(["-u", SERVICE_NAME, "-f", "--no-pager", "-n", "100"])
+        .status()?;
+    std::process::exit(status.code().unwrap_or(1));
+}
+
+/// `aether-proxy start` -- start the service.
+pub fn cmd_start() -> anyhow::Result<()> {
+    ensure_root_and_service()?;
+    run_cmd("systemctl", &["start", SERVICE_NAME])?;
+    eprintln!("  Service started.");
+    Ok(())
+}
+
+/// `aether-proxy restart` -- restart the service.
+pub fn cmd_restart() -> anyhow::Result<()> {
+    ensure_root_and_service()?;
+    run_cmd("systemctl", &["restart", SERVICE_NAME])?;
+    eprintln!("  Service restarted.");
+    Ok(())
+}
+
+/// `aether-proxy stop` -- stop the service.
+pub fn cmd_stop() -> anyhow::Result<()> {
+    ensure_root_and_service()?;
+    run_cmd("systemctl", &["stop", SERVICE_NAME])?;
+    eprintln!("  Service stopped.");
+    Ok(())
+}
+
+/// `aether-proxy uninstall` -- disable and remove the systemd service.
+pub fn cmd_uninstall() -> anyhow::Result<()> {
+    ensure_root_and_service()?;
+
+    eprintln!("  Stopping and disabling service...");
+    let _ = Command::new("systemctl")
+        .args(["disable", "--now", SERVICE_NAME])
+        .status();
+
+    if std::path::Path::new(UNIT_PATH).exists() {
+        std::fs::remove_file(UNIT_PATH)?;
+        eprintln!("  Removed {}", UNIT_PATH);
+    }
+
+    run_cmd("systemctl", &["daemon-reload"])?;
+    eprintln!("  Service uninstalled.");
+    eprintln!();
+    eprintln!("  Config file and TLS certs are preserved. Remove manually if needed.");
+
+    Ok(())
+}
+
+pub(crate) fn run_cmd(program: &str, args: &[&str]) -> anyhow::Result<()> {
+    let display = format!("{} {}", program, args.join(" "));
+    eprintln!("  > {}", display);
+
+    let status = Command::new(program).args(args).status()?;
+    if !status.success() {
+        anyhow::bail!("command failed: {}", display);
+    }
+    Ok(())
+}

apps/aether-proxy/src/setup/tui.rs

@@ -0,0 +1,868 @@
+//! Interactive TUI for configuring aether-proxy.
+//!
+//! Launched via `aether-proxy setup [path]`.  Presents a full-screen form
+//! backed by ratatui where the user can navigate fields, edit values, and
+//! save to a TOML config file.  Supports multi-server configuration via
+//! a tabbed interface.
+
+use std::io;
+use std::path::PathBuf;
+use std::time::{Duration, Instant};
+
+use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind, KeyModifiers};
+use crossterm::execute;
+use crossterm::terminal::{self, EnterAlternateScreen, LeaveAlternateScreen};
+use ratatui::backend::CrosstermBackend;
+use ratatui::layout::{Constraint, Layout, Rect};
+use ratatui::style::{Color, Modifier, Style};
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Borders, Paragraph};
+use ratatui::Frame;
+use ratatui::Terminal;
+
+use crate::config::{ConfigFile, ServerEntry};
+
+/// Outcome of the setup wizard, returned to the caller.
+pub enum SetupOutcome {
+    /// Config saved; systemd service installed and started.
+    ServiceInstalled,
+    /// Config saved; no service -- caller should start the proxy directly.
+    ReadyToRun(PathBuf),
+    /// User quit without saving.
+    Cancelled,
+}
+
+/// Column width reserved for the field label (chars).
+const LABEL_WIDTH: usize = 22;
+
+// -- Field types --------------------------------------------------------------
+
+#[derive(Clone, Copy, PartialEq)]
+enum FieldKind {
+    Text,
+    Secret,
+    Bool,
+    LogLevel,
+}
+
+struct Field {
+    label: &'static str,
+    key: &'static str,
+    value: String,
+    kind: FieldKind,
+    required: bool,
+    help: &'static str,
+}
+// -- Server tab ---------------------------------------------------------------
+
+/// A single server tab's editable fields.
+struct ServerTab {
+    fields: Vec<Field>,
+}
+
+impl ServerTab {
+    fn new() -> Self {
+        Self {
+            fields: vec![
+                Field {
+                    label: "Aether URL",
+                    key: "aether_url",
+                    value: String::new(),
+                    kind: FieldKind::Text,
+                    required: true,
+                    help: "Aether URL (e.g. https://aether.example.com)",
+                },
+                Field {
+                    label: "Management Token",
+                    key: "management_token",
+                    value: String::new(),
+                    kind: FieldKind::Secret,
+                    required: true,
+                    help: "Aether Management Token (ae_xxx)",
+                },
+                Field {
+                    label: "Node Name",
+                    key: "node_name",
+                    value: "proxy-01".into(),
+                    kind: FieldKind::Text,
+                    required: true,
+                    help: "Node name for identification in Aether dashboard",
+                },
+            ],
+        }
+    }
+
+    fn from_entry(entry: &ServerEntry) -> Self {
+        let mut tab = Self::new();
+        tab.fields[0].value = entry.aether_url.clone();
+        tab.fields[1].value = entry.management_token.clone();
+        if let Some(ref name) = entry.node_name {
+            tab.fields[2].value = name.clone();
+        }
+        tab
+    }
+}
+
+// -- App state ----------------------------------------------------------------
+
+#[derive(PartialEq)]
+enum Mode {
+    Normal,
+    Editing,
+}
+
+struct App {
+    server_tabs: Vec<ServerTab>,
+    active_tab: usize,
+    global_fields: Vec<Field>,
+    selected: usize,
+    mode: Mode,
+    edit_buffer: String,
+    edit_cursor: usize,
+    config_path: PathBuf,
+    modified: bool,
+    message: Option<(String, Instant, bool)>,
+    scroll_offset: usize,
+    saved_once: bool,
+    pending_quit: bool,
+    confirm_delete: bool,
+}
+impl App {
+    fn new(config_path: PathBuf) -> Self {
+        Self {
+            server_tabs: vec![ServerTab::new()],
+            active_tab: 0,
+            global_fields: vec![
+                Field {
+                    label: "Log Level",
+                    key: "log_level",
+                    value: "info".into(),
+                    kind: FieldKind::LogLevel,
+                    required: true,
+                    help: "Log level -- Enter to cycle: trace / debug / info / warn / error",
+                },
+                Field {
+                    label: "Log JSON",
+                    key: "log_json",
+                    value: "false".into(),
+                    kind: FieldKind::Bool,
+                    required: true,
+                    help: "Output logs as JSON -- Enter to toggle",
+                },
+                Field {
+                    label: "Install Service",
+                    key: "install_service",
+                    value: if super::service::is_available() {
+                        "true"
+                    } else {
+                        "false"
+                    }
+                    .into(),
+                    kind: FieldKind::Bool,
+                    required: true,
+                    help: "Install as systemd service (requires root) -- Enter to toggle",
+                },
+            ],
+            selected: 0,
+            mode: Mode::Normal,
+            edit_buffer: String::new(),
+            edit_cursor: 0,
+            config_path,
+            modified: false,
+            message: None,
+            scroll_offset: 0,
+            saved_once: false,
+            pending_quit: false,
+            confirm_delete: false,
+        }
+    }
+
+    // -- Field accessors (unified index across server + global) ---------------
+
+    fn server_field_count(&self) -> usize {
+        self.server_tabs[self.active_tab].fields.len()
+    }
+
+    fn total_field_count(&self) -> usize {
+        self.server_field_count() + self.global_fields.len()
+    }
+
+    fn selected_field(&self) -> &Field {
+        let sc = self.server_field_count();
+        if self.selected < sc {
+            &self.server_tabs[self.active_tab].fields[self.selected]
+        } else {
+            &self.global_fields[self.selected - sc]
+        }
+    }
+
+    fn selected_field_mut(&mut self) -> &mut Field {
+        let sc = self.server_field_count();
+        if self.selected < sc {
+            &mut self.server_tabs[self.active_tab].fields[self.selected]
+        } else {
+            &mut self.global_fields[self.selected - sc]
+        }
+    }
+
+    fn clamp_selection(&mut self) {
+        let max = self.total_field_count();
+        if self.selected >= max {
+            self.selected = max.saturating_sub(1);
+        }
+        self.scroll_offset = 0;
+        self.confirm_delete = false;
+    }
+    // -- Config <-> fields -----------------------------------------------------
+
+    fn load_from_file(&mut self) {
+        if let Ok(cfg) = ConfigFile::load(&self.config_path) {
+            self.apply_config(&cfg);
+        }
+    }
+
+    fn apply_config(&mut self, cfg: &ConfigFile) {
+        // Global fields
+        for field in &mut self.global_fields {
+            let val: Option<String> = match field.key {
+                "log_level" => cfg.log_level.clone(),
+                "log_json" => cfg.log_json.map(|v| v.to_string()),
+                _ => None,
+            };
+            if let Some(v) = val {
+                field.value = v;
+            }
+        }
+
+        // Server tabs
+        let servers = cfg.effective_servers();
+        if servers.is_empty() {
+            let mut tab = ServerTab::new();
+            // Single-server fallback: use top-level node_name
+            if let Some(ref name) = cfg.node_name {
+                tab.fields[2].value = name.clone();
+            }
+            self.server_tabs = vec![tab];
+        } else {
+            self.server_tabs = servers.iter().map(ServerTab::from_entry).collect();
+            // For single-server mode, node_name might be in top-level only
+            if self.server_tabs.len() == 1 && self.server_tabs[0].fields[2].value.is_empty() {
+                if let Some(ref name) = cfg.node_name {
+                    self.server_tabs[0].fields[2].value = name.clone();
+                }
+            }
+        }
+        self.active_tab = 0;
+        self.selected = 0;
+        self.scroll_offset = 0;
+    }
+
+    fn to_config(&self) -> ConfigFile {
+        let get_global = |key: &str| -> Option<String> {
+            self.global_fields
+                .iter()
+                .find(|f| f.key == key)
+                .map(|f| f.value.clone())
+                .filter(|v| !v.is_empty())
+        };
+
+        let get_tab = |tab: &ServerTab, key: &str| -> Option<String> {
+            tab.fields
+                .iter()
+                .find(|f| f.key == key)
+                .map(|f| f.value.clone())
+                .filter(|v| !v.is_empty())
+        };
+
+        let mut cfg = ConfigFile {
+            log_level: get_global("log_level"),
+            log_json: get_global("log_json").and_then(|v| v.parse().ok()),
+            ..ConfigFile::default()
+        };
+
+        // Always write [[servers]] format; old top-level fields are read-only compat
+        cfg.servers = self
+            .server_tabs
+            .iter()
+            .map(|tab| ServerEntry {
+                aether_url: get_tab(tab, "aether_url").unwrap_or_default(),
+                management_token: get_tab(tab, "management_token").unwrap_or_default(),
+                node_name: get_tab(tab, "node_name"),
+            })
+            .collect();
+        cfg
+    }
+
+    fn save(&mut self) -> anyhow::Result<()> {
+        let cfg = self.to_config();
+        cfg.save(&self.config_path)?;
+        // Restrict config file permissions to owner-only (contains management token).
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let _ =
+                std::fs::set_permissions(&self.config_path, std::fs::Permissions::from_mode(0o600));
+        }
+        self.modified = false;
+        self.saved_once = true;
+        self.message = Some((
+            format!("saved to {}", self.config_path.display()),
+            Instant::now(),
+            false,
+        ));
+        Ok(())
+    }
+    // -- Scrolling ---------------------------------------------------------------
+
+    fn ensure_visible(&mut self, visible_rows: usize) {
+        if visible_rows == 0 {
+            return;
+        }
+        // Account for separator line between server and global fields
+        let display_row = if self.selected >= self.server_field_count() {
+            self.selected + 1
+        } else {
+            self.selected
+        };
+        if display_row < self.scroll_offset {
+            self.scroll_offset = display_row;
+        } else if display_row >= self.scroll_offset + visible_rows {
+            self.scroll_offset = display_row - visible_rows + 1;
+        }
+    }
+
+    // -- Key handling -------------------------------------------------------------
+
+    /// Returns `true` when the app should exit.
+    fn handle_key(&mut self, key: KeyEvent) -> bool {
+        // Expire old messages (but keep quit-confirmation messages alive)
+        if let Some((_, when, _)) = &self.message {
+            if !self.pending_quit && !self.confirm_delete && when.elapsed() > Duration::from_secs(4)
+            {
+                self.message = None;
+            }
+        }
+
+        match self.mode {
+            Mode::Normal => self.handle_normal(key),
+            Mode::Editing => {
+                self.handle_edit(key);
+                false
+            }
+        }
+    }
+
+    fn handle_normal(&mut self, key: KeyEvent) -> bool {
+        // -- Quit handling (with unsaved-changes confirmation) -----------------
+        let is_quit_key = matches!(key.code, KeyCode::Char('q') | KeyCode::Esc);
+
+        if is_quit_key {
+            if !self.modified || self.pending_quit {
+                return true;
+            }
+            self.pending_quit = true;
+            self.confirm_delete = false;
+            self.message = Some((
+                "unsaved changes! q again to discard, ^S to save".into(),
+                Instant::now(),
+                true,
+            ));
+            return false;
+        }
+
+        // Any other key cancels pending quit / pending delete
+        if self.pending_quit {
+            self.pending_quit = false;
+            self.message = None;
+        }
+        if self.confirm_delete && !matches!(key.code, KeyCode::Delete | KeyCode::Char('x')) {
+            self.confirm_delete = false;
+            self.message = None;
+        }
+
+        match key.code {
+            KeyCode::Char('s')
+                if key.modifiers.contains(KeyModifiers::CONTROL)
+                    || key.modifiers.contains(KeyModifiers::SUPER) =>
+            {
+                if let Err(e) = self.save() {
+                    self.message = Some((format!("error: {}", e), Instant::now(), true));
+                }
+            }
+            KeyCode::Up | KeyCode::Char('k') => {
+                self.selected = self.selected.saturating_sub(1);
+            }
+            KeyCode::Down | KeyCode::Char('j') => {
+                if self.selected + 1 < self.total_field_count() {
+                    self.selected += 1;
+                }
+            }
+            KeyCode::Home => self.selected = 0,
+            KeyCode::End => self.selected = self.total_field_count() - 1,
+            KeyCode::Enter | KeyCode::Char(' ') => {
+                let kind = self.selected_field().kind;
+                let key_str = self.selected_field().key;
+                let value = self.selected_field().value.clone();
+                match kind {
+                    FieldKind::Bool => {
+                        let toggled = if value == "true" { "false" } else { "true" };
+                        if key_str == "install_service"
+                            && toggled == "true"
+                            && !super::service::is_available()
+                        {
+                            self.message = Some((
+                                "requires root with systemd, use: sudo aether-proxy setup".into(),
+                                Instant::now(),
+                                true,
+                            ));
+                        } else {
+                            self.selected_field_mut().value = toggled.into();
+                            self.modified = true;
+                        }
+                    }
+                    FieldKind::LogLevel => {
+                        const LEVELS: &[&str] = &["trace", "debug", "info", "warn", "error"];
+                        let idx = LEVELS.iter().position(|l| *l == value).unwrap_or(2);
+                        self.selected_field_mut().value = LEVELS[(idx + 1) % LEVELS.len()].into();
+                        self.modified = true;
+                    }
+                    _ => {
+                        self.edit_buffer = value;
+                        self.edit_cursor = self.edit_buffer.chars().count();
+                        self.mode = Mode::Editing;
+                    }
+                }
+            }
+            // -- Tab navigation --
+            KeyCode::Tab => {
+                if self.server_tabs.len() > 1 {
+                    self.active_tab = (self.active_tab + 1) % self.server_tabs.len();
+                    self.clamp_selection();
+                }
+            }
+            KeyCode::BackTab => {
+                if self.server_tabs.len() > 1 {
+                    self.active_tab = if self.active_tab == 0 {
+                        self.server_tabs.len() - 1
+                    } else {
+                        self.active_tab - 1
+                    };
+                    self.clamp_selection();
+                }
+            }
+            KeyCode::Char(c @ '1'..='9') if !key.modifiers.contains(KeyModifiers::CONTROL) => {
+                let idx = (c as usize) - ('1' as usize);
+                if idx < self.server_tabs.len() && idx != self.active_tab {
+                    self.active_tab = idx;
+                    self.clamp_selection();
+                }
+            }
+            // -- Add / remove server --
+            KeyCode::Char('+') | KeyCode::Char('a') => {
+                self.server_tabs.push(ServerTab::new());
+                self.active_tab = self.server_tabs.len() - 1;
+                self.selected = 0;
+                self.scroll_offset = 0;
+                self.modified = true;
+                self.message = Some((
+                    format!("added server {}", self.server_tabs.len()),
+                    Instant::now(),
+                    false,
+                ));
+            }
+            KeyCode::Delete | KeyCode::Char('x') => {
+                if self.server_tabs.len() <= 1 {
+                    self.message =
+                        Some(("cannot remove the last server".into(), Instant::now(), true));
+                } else if self.confirm_delete {
+                    let removed = self.active_tab + 1;
+                    self.server_tabs.remove(self.active_tab);
+                    self.active_tab = self.active_tab.min(self.server_tabs.len() - 1);
+                    self.clamp_selection();
+                    self.modified = true;
+                    self.message =
+                        Some((format!("server {} removed", removed), Instant::now(), false));
+                } else {
+                    self.confirm_delete = true;
+                    self.message = Some((
+                        "press Delete/x again to remove this server".into(),
+                        Instant::now(),
+                        true,
+                    ));
+                }
+            }
+            _ => {}
+        }
+        false
+    }
+
+    fn handle_edit(&mut self, key: KeyEvent) {
+        match key.code {
+            KeyCode::Esc => {
+                self.mode = Mode::Normal;
+            }
+            KeyCode::Enter => {
+                if self.validate_edit() {
+                    self.selected_field_mut().value = self.edit_buffer.clone();
+                    self.modified = true;
+                    self.mode = Mode::Normal;
+                } else {
+                    self.message = Some(("invalid format".into(), Instant::now(), true));
+                }
+            }
+            KeyCode::Backspace => {
+                if self.edit_cursor > 0 {
+                    self.edit_cursor -= 1;
+                    let byte = self.char_byte_pos(self.edit_cursor);
+                    self.edit_buffer.remove(byte);
+                }
+            }
+            KeyCode::Delete => {
+                if self.edit_cursor < self.edit_buffer.chars().count() {
+                    let byte = self.char_byte_pos(self.edit_cursor);
+                    self.edit_buffer.remove(byte);
+                }
+            }
+            KeyCode::Left => {
+                self.edit_cursor = self.edit_cursor.saturating_sub(1);
+            }
+            KeyCode::Right => {
+                let len = self.edit_buffer.chars().count();
+                if self.edit_cursor < len {
+                    self.edit_cursor += 1;
+                }
+            }
+            KeyCode::Home => self.edit_cursor = 0,
+            KeyCode::End => self.edit_cursor = self.edit_buffer.chars().count(),
+            KeyCode::Char(c) => {
+                let byte = self.char_byte_pos(self.edit_cursor);
+                self.edit_buffer.insert(byte, c);
+                self.edit_cursor += 1;
+            }
+            _ => {}
+        }
+    }
+
+    fn validate_edit(&self) -> bool {
+        true
+    }
+
+    /// Byte offset of the char at `char_idx`.
+    fn char_byte_pos(&self, char_idx: usize) -> usize {
+        self.edit_buffer
+            .char_indices()
+            .nth(char_idx)
+            .map(|(i, _)| i)
+            .unwrap_or(self.edit_buffer.len())
+    }
+}
+// -- Rendering ----------------------------------------------------------------
+
+fn ui(f: &mut Frame, app: &mut App) {
+    let area = f.area();
+
+    let title = if app.modified {
+        " Aether Proxy Setup [*] "
+    } else {
+        " Aether Proxy Setup "
+    };
+
+    let outer = Block::default()
+        .borders(Borders::ALL)
+        .title(title)
+        .title_alignment(ratatui::layout::Alignment::Center)
+        .border_style(Style::default().fg(Color::Cyan));
+
+    let inner = outer.inner(area);
+    f.render_widget(outer, area);
+
+    // Split: fields | tab bar | footer
+    let chunks = Layout::vertical([
+        Constraint::Min(1),
+        Constraint::Length(1),
+        Constraint::Length(4),
+    ])
+    .split(inner);
+
+    render_fields(f, app, chunks[0]);
+    render_tab_bar(f, app, chunks[1]);
+    render_footer(f, app, chunks[2]);
+}
+
+fn render_fields(f: &mut Frame, app: &mut App, area: Rect) {
+    let visible = area.height as usize;
+    app.ensure_visible(visible);
+
+    let server_count = app.server_field_count();
+    let mut lines: Vec<Line> = Vec::new();
+    // display_row tracks the actual row index (including separator)
+    let mut display_row: usize = 0;
+
+    // Server fields
+    for i in 0..server_count {
+        if display_row >= app.scroll_offset && display_row < app.scroll_offset + visible {
+            lines.push(build_field_line(app, i, display_row));
+        }
+        display_row += 1;
+    }
+
+    // Separator line
+    if display_row >= app.scroll_offset && display_row < app.scroll_offset + visible {
+        lines.push(Line::from(Span::styled(
+            "   ----------------------------------------",
+            Style::default().fg(Color::DarkGray),
+        )));
+    }
+    display_row += 1;
+
+    // Global fields
+    for i in 0..app.global_fields.len() {
+        let field_idx = server_count + i;
+        if display_row >= app.scroll_offset && display_row < app.scroll_offset + visible {
+            lines.push(build_field_line(app, field_idx, display_row));
+        }
+        display_row += 1;
+    }
+
+    let paragraph = Paragraph::new(lines);
+    f.render_widget(paragraph, area);
+
+    // Cursor position while editing
+    if app.mode == Mode::Editing {
+        let sel_display_row = if app.selected >= server_count {
+            app.selected + 1
+        } else {
+            app.selected
+        };
+        let row_in_view = sel_display_row.saturating_sub(app.scroll_offset);
+        let prefix: u16 = 3 + LABEL_WIDTH as u16 + 2;
+        let cx = area.x + prefix + app.edit_cursor as u16;
+        let cy = area.y + row_in_view as u16;
+        if cx < area.x + area.width && cy < area.y + area.height {
+            f.set_cursor_position((cx, cy));
+        }
+    }
+}
+fn build_field_line(app: &App, field_idx: usize, _display_row: usize) -> Line<'static> {
+    let sc = app.server_field_count();
+    let field = if field_idx < sc {
+        &app.server_tabs[app.active_tab].fields[field_idx]
+    } else {
+        &app.global_fields[field_idx - sc]
+    };
+
+    let selected = field_idx == app.selected;
+    let indicator = if selected { " > " } else { "   " };
+
+    let label_style = if selected {
+        Style::default()
+            .fg(Color::Cyan)
+            .add_modifier(Modifier::BOLD)
+    } else {
+        Style::default().fg(Color::DarkGray)
+    };
+
+    let padded_label = format!("{:<width$}", field.label, width = LABEL_WIDTH);
+
+    let (value_text, value_style) = if app.mode == Mode::Editing && selected {
+        (app.edit_buffer.clone(), Style::default().fg(Color::Yellow))
+    } else {
+        field_display(field)
+    };
+
+    Line::from(vec![
+        Span::styled(indicator.to_string(), label_style),
+        Span::styled(padded_label, label_style),
+        Span::raw("  "),
+        Span::styled(value_text, value_style),
+    ])
+}
+
+/// Returns (display_text, style) for a field in normal mode.
+fn field_display(field: &Field) -> (String, Style) {
+    if field.value.is_empty() {
+        let text = if field.required {
+            "(required)".into()
+        } else {
+            "-".into()
+        };
+        let color = if field.required {
+            Color::Red
+        } else {
+            Color::DarkGray
+        };
+        return (text, Style::default().fg(color));
+    }
+
+    match field.kind {
+        FieldKind::Secret => (
+            "*".repeat(field.value.len().min(20)),
+            Style::default().fg(Color::White),
+        ),
+        FieldKind::Bool => {
+            if field.value == "true" {
+                ("[x] on".into(), Style::default().fg(Color::Green))
+            } else {
+                ("[ ] off".into(), Style::default().fg(Color::DarkGray))
+            }
+        }
+        FieldKind::LogLevel => {
+            let color = match field.value.as_str() {
+                "trace" => Color::Magenta,
+                "debug" => Color::Blue,
+                "info" => Color::Green,
+                "warn" => Color::Yellow,
+                "error" => Color::Red,
+                _ => Color::White,
+            };
+            (field.value.clone(), Style::default().fg(color))
+        }
+        _ => (field.value.clone(), Style::default().fg(Color::White)),
+    }
+}
+fn render_tab_bar(f: &mut Frame, app: &App, area: Rect) {
+    let mut spans: Vec<Span> = Vec::new();
+    spans.push(Span::raw(" "));
+
+    for (i, tab) in app.server_tabs.iter().enumerate() {
+        let num = i + 1;
+        let name = tab
+            .fields
+            .iter()
+            .find(|f| f.key == "node_name")
+            .filter(|f| !f.value.is_empty())
+            .map(|f| f.value.clone())
+            .unwrap_or_else(|| format!("Server {}", num));
+
+        let label = format!(" {} {} ", num, name);
+
+        if i == app.active_tab {
+            spans.push(Span::styled(
+                label,
+                Style::default()
+                    .fg(Color::Black)
+                    .bg(Color::Cyan)
+                    .add_modifier(Modifier::BOLD),
+            ));
+        } else {
+            spans.push(Span::styled(label, Style::default().fg(Color::DarkGray)));
+        }
+        spans.push(Span::raw(" "));
+    }
+
+    spans.push(Span::styled(" + Add ", Style::default().fg(Color::Green)));
+
+    f.render_widget(Paragraph::new(Line::from(spans)), area);
+}
+
+fn render_footer(f: &mut Frame, app: &App, area: Rect) {
+    let help = app.selected_field().help;
+
+    let keybindings = if app.mode == Mode::Editing {
+        "Enter confirm  Esc cancel"
+    } else if app.server_tabs.len() > 1 {
+        "j/k select  Enter edit  Tab switch  + add  x remove  ^S save  q quit"
+    } else {
+        "j/k select  Enter edit  + add server  ^S save  q quit"
+    };
+
+    let mut status_spans: Vec<Span> = vec![Span::styled(
+        format!(" {}", keybindings),
+        Style::default().fg(Color::DarkGray),
+    )];
+
+    if let Some((msg, _, is_err)) = &app.message {
+        let color = if *is_err { Color::Red } else { Color::Green };
+        status_spans.push(Span::raw("    "));
+        status_spans.push(Span::styled(msg.clone(), Style::default().fg(color)));
+    }
+
+    let footer_text = vec![
+        Line::raw(""),
+        Line::from(Span::styled(
+            format!(" {}", help),
+            Style::default().fg(Color::DarkGray),
+        )),
+        Line::from(status_spans),
+    ];
+
+    let footer = Paragraph::new(footer_text).block(
+        Block::default()
+            .borders(Borders::TOP)
+            .border_style(Style::default().fg(Color::DarkGray)),
+    );
+
+    f.render_widget(footer, area);
+}
+// -- Entry point --------------------------------------------------------------
+
+pub fn run(config_path: PathBuf) -> anyhow::Result<SetupOutcome> {
+    terminal::enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    let mut app = App::new(config_path.clone());
+    app.load_from_file();
+
+    let result = event_loop(&mut terminal, &mut app);
+
+    terminal::disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+    terminal.show_cursor()?;
+
+    result?;
+
+    // -- Post-TUI: decide outcome ---------------------------------------------
+
+    if !app.saved_once {
+        return Ok(SetupOutcome::Cancelled);
+    }
+
+    eprintln!();
+    eprintln!("  Config saved to {}", config_path.display());
+    eprintln!();
+
+    let wants_service = app
+        .global_fields
+        .iter()
+        .find(|f| f.key == "install_service")
+        .map(|f| f.value == "true")
+        .unwrap_or(false);
+
+    if wants_service {
+        match super::service::install_service(&config_path) {
+            Ok(()) => return Ok(SetupOutcome::ServiceInstalled),
+            Err(e) => {
+                eprintln!("  Service install failed: {}", e);
+                eprintln!("  Starting proxy directly instead.\n");
+            }
+        }
+    } else if super::service::is_installed() {
+        if let Err(e) = super::service::uninstall_service() {
+            eprintln!("  Service uninstall failed: {}", e);
+            eprintln!();
+        }
+    }
+
+    Ok(SetupOutcome::ReadyToRun(config_path))
+}
+
+fn event_loop(
+    terminal: &mut Terminal<CrosstermBackend<io::Stdout>>,
+    app: &mut App,
+) -> anyhow::Result<()> {
+    loop {
+        terminal.draw(|f| ui(f, app))?;
+
+        if event::poll(Duration::from_millis(200))? {
+            if let Event::Key(key) = event::read()? {
+                if key.kind == KeyEventKind::Press && app.handle_key(key) {
+                    break;
+                }
+            }
+        }
+    }
+    Ok(())
+}

apps/aether-proxy/src/setup/upgrade.rs

@@ -0,0 +1,416 @@
+//! Self-upgrade for aether-proxy.
+//!
+//! Downloads a release from GitHub, verifies SHA256 checksum, and atomically
+//! replaces the running binary.  Restarts the systemd service if active.
+
+use std::path::{Path, PathBuf};
+
+use aether_http::{apply_http_client_config, HttpClientConfig};
+use sha2::{Digest, Sha256};
+
+const GITHUB_API_BASE: &str = "https://api.github.com";
+const GITHUB_REPO: &str = "fawney19/Aether";
+const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+// ── GitHub API types ─────────────────────────────────────────────────────────
+
+#[derive(serde::Deserialize)]
+struct GithubRelease {
+    tag_name: String,
+    name: String,
+}
+
+// ── Platform detection ───────────────────────────────────────────────────────
+
+fn detect_platform() -> &'static str {
+    if cfg!(target_os = "linux") && cfg!(target_arch = "x86_64") {
+        "linux-amd64"
+    } else if cfg!(target_os = "linux") && cfg!(target_arch = "aarch64") {
+        "linux-arm64"
+    } else if cfg!(target_os = "macos") && cfg!(target_arch = "x86_64") {
+        "macos-amd64"
+    } else if cfg!(target_os = "macos") && cfg!(target_arch = "aarch64") {
+        "macos-arm64"
+    } else if cfg!(target_os = "windows") && cfg!(target_arch = "x86_64") {
+        "windows-amd64"
+    } else {
+        // All supported targets are covered above; this is unreachable for
+        // any platform we actually build for.
+        panic!("unsupported platform: compile-time target not in the supported matrix")
+    }
+}
+
+// ── GitHub HTTP client ───────────────────────────────────────────────────────
+
+fn build_github_client() -> anyhow::Result<reqwest::Client> {
+    let mut headers = reqwest::header::HeaderMap::new();
+
+    if let Ok(token) = std::env::var("GITHUB_TOKEN") {
+        headers.insert(
+            reqwest::header::AUTHORIZATION,
+            reqwest::header::HeaderValue::from_str(&format!("Bearer {}", token))?,
+        );
+    }
+
+    headers.insert(
+        reqwest::header::ACCEPT,
+        reqwest::header::HeaderValue::from_static("application/vnd.github+json"),
+    );
+
+    Ok(apply_http_client_config(
+        reqwest::Client::builder().default_headers(headers),
+        &HttpClientConfig {
+            request_timeout_ms: Some(300_000),
+            user_agent: Some(format!("aether-proxy/{}", CURRENT_VERSION)),
+            ..HttpClientConfig::default()
+        },
+    )
+    .build()?)
+}
+
+// ── Release fetching ─────────────────────────────────────────────────────────
+
+async fn fetch_release(
+    client: &reqwest::Client,
+    version: Option<&str>,
+) -> anyhow::Result<GithubRelease> {
+    match version {
+        Some(ver) => {
+            // Accept both "proxy-v0.2.0" and bare "0.2.0"
+            let tag = if ver.starts_with("proxy-v") {
+                ver.to_string()
+            } else {
+                format!("proxy-v{}", ver)
+            };
+            let url = format!(
+                "{}/repos/{}/releases/tags/{}",
+                GITHUB_API_BASE, GITHUB_REPO, tag
+            );
+            let resp = client.get(&url).send().await?;
+            if !resp.status().is_success() {
+                let status = resp.status();
+                let body = resp.text().await.unwrap_or_default();
+                anyhow::bail!("release '{}' not found (HTTP {}): {}", tag, status, body);
+            }
+            Ok(resp.json().await?)
+        }
+        None => {
+            // List releases and find the latest proxy-v* tag
+            let url = format!(
+                "{}/repos/{}/releases?per_page=20",
+                GITHUB_API_BASE, GITHUB_REPO
+            );
+            let resp = client.get(&url).send().await?;
+            if !resp.status().is_success() {
+                let status = resp.status();
+                let body = resp.text().await.unwrap_or_default();
+                anyhow::bail!("failed to list releases (HTTP {}): {}", status, body);
+            }
+            let releases: Vec<GithubRelease> = resp.json().await?;
+            releases
+                .into_iter()
+                .find(|r| r.tag_name.starts_with("proxy-v"))
+                .ok_or_else(|| anyhow::anyhow!("no proxy-v* release found"))
+        }
+    }
+}
+
+// ── Download via GitHub release direct links ─────────────────────────────────
+
+/// Download a release asset via the public direct download URL:
+/// `https://github.com/{repo}/releases/download/{tag}/{filename}`
+async fn download_release_file(
+    client: &reqwest::Client,
+    tag: &str,
+    filename: &str,
+) -> anyhow::Result<Vec<u8>> {
+    let url = format!(
+        "https://github.com/{}/releases/download/{}/{}",
+        GITHUB_REPO, tag, filename
+    );
+    let resp = client
+        .get(&url)
+        .header(reqwest::header::ACCEPT, "application/octet-stream")
+        .send()
+        .await?;
+    if !resp.status().is_success() {
+        anyhow::bail!(
+            "download failed for '{}' (HTTP {})",
+            filename,
+            resp.status(),
+        );
+    }
+    Ok(resp.bytes().await?.to_vec())
+}
+
+fn parse_checksum(sums_text: &str, filename: &str) -> anyhow::Result<String> {
+    for line in sums_text.lines() {
+        // Format: "<hash>  <filename>" (GNU coreutils convention)
+        let mut parts = line.split_ascii_whitespace();
+        let (Some(hash), Some(name)) = (parts.next(), parts.next()) else {
+            continue;
+        };
+        if name == filename || name.ends_with(filename) {
+            return Ok(hash.to_lowercase());
+        }
+    }
+    anyhow::bail!("checksum for '{}' not found in SHA256SUMS.txt", filename);
+}
+
+async fn download_and_verify(
+    client: &reqwest::Client,
+    tag: &str,
+    platform: &str,
+    dest: &Path,
+) -> anyhow::Result<()> {
+    let archive_name = format!("aether-proxy-{}.tar.gz", platform);
+
+    eprintln!("  Downloading {}...", archive_name);
+    let (archive_bytes, checksum_bytes) = tokio::try_join!(
+        download_release_file(client, tag, &archive_name),
+        download_release_file(client, tag, "SHA256SUMS.txt"),
+    )?;
+    let checksum_text = String::from_utf8(checksum_bytes)?;
+
+    eprintln!(
+        "  Downloaded {} ({} bytes)",
+        archive_name,
+        archive_bytes.len()
+    );
+
+    // Verify SHA256
+    let expected_hash = parse_checksum(&checksum_text, &archive_name)?;
+    let mut hasher = Sha256::new();
+    hasher.update(&archive_bytes);
+    let actual_hash = hex::encode(hasher.finalize());
+
+    if actual_hash != expected_hash {
+        anyhow::bail!(
+            "SHA256 mismatch for {}:\n  expected: {}\n  actual:   {}",
+            archive_name,
+            expected_hash,
+            actual_hash
+        );
+    }
+    eprintln!("  SHA256 verified: {}", &actual_hash[..16]);
+
+    extract_binary(&archive_bytes, dest)?;
+
+    Ok(())
+}
+
+// ── Archive extraction ───────────────────────────────────────────────────────
+
+fn extract_binary(archive_bytes: &[u8], dest: &Path) -> anyhow::Result<()> {
+    use flate2::read::GzDecoder;
+    use tar::Archive;
+
+    // Guard against decompression bombs
+    const MAX_BINARY_SIZE: u64 = 100 * 1024 * 1024; // 100 MB
+
+    let decoder = GzDecoder::new(archive_bytes);
+    let mut archive = Archive::new(decoder);
+
+    let binary_name = if cfg!(target_os = "windows") {
+        "aether-proxy.exe"
+    } else {
+        "aether-proxy"
+    };
+
+    for entry in archive.entries()? {
+        let mut entry = entry?;
+        // Only accept regular files -- reject symlinks to prevent write-through attacks
+        if entry.header().entry_type() != tar::EntryType::Regular {
+            continue;
+        }
+        let path = entry.path()?;
+        if path.file_name().and_then(|n| n.to_str()) == Some(binary_name) {
+            let size = entry.header().size()?;
+            if size > MAX_BINARY_SIZE {
+                anyhow::bail!(
+                    "binary too large ({} bytes, max {} bytes)",
+                    size,
+                    MAX_BINARY_SIZE
+                );
+            }
+            let mut file = std::fs::File::create(dest)?;
+            std::io::copy(&mut entry, &mut file)?;
+
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                std::fs::set_permissions(dest, std::fs::Permissions::from_mode(0o755))?;
+            }
+
+            return Ok(());
+        }
+    }
+
+    anyhow::bail!("'{}' not found in archive", binary_name);
+}
+
+// ── Atomic binary replacement ────────────────────────────────────────────────
+
+fn atomic_replace(new_binary: &Path) -> anyhow::Result<PathBuf> {
+    let current_exe = std::env::current_exe()?.canonicalize()?;
+    let backup_path = current_exe.with_extension("bak");
+
+    // Remove stale backup
+    let _ = std::fs::remove_file(&backup_path);
+
+    // current -> .bak
+    std::fs::rename(&current_exe, &backup_path).map_err(|e| {
+        anyhow::anyhow!(
+            "failed to backup current binary '{}' -> '{}': {}",
+            current_exe.display(),
+            backup_path.display(),
+            e
+        )
+    })?;
+
+    // new -> current
+    if let Err(e) = std::fs::rename(new_binary, &current_exe) {
+        eprintln!("  ERROR: failed to place new binary, rolling back...");
+        let _ = std::fs::rename(&backup_path, &current_exe);
+        anyhow::bail!(
+            "failed to install new binary '{}' -> '{}': {}",
+            new_binary.display(),
+            current_exe.display(),
+            e
+        );
+    }
+
+    eprintln!("  Binary replaced: {}", current_exe.display());
+    Ok(backup_path)
+}
+
+// ── Public entry point ───────────────────────────────────────────────────────
+
+#[derive(Clone, Copy)]
+enum RestartMode {
+    BestEffort,
+    Required,
+}
+
+async fn execute_upgrade(
+    version: Option<&str>,
+    require_root: bool,
+    restart_mode: RestartMode,
+) -> anyhow::Result<()> {
+    // Resolve exe path once; reuse throughout the function
+    let current_exe = std::env::current_exe()?.canonicalize()?;
+    let exe_dir = current_exe
+        .parent()
+        .ok_or_else(|| anyhow::anyhow!("cannot determine binary directory"))?;
+    let temp_path = exe_dir.join(".aether-proxy.upgrade.tmp");
+
+    if require_root {
+        if !super::service::is_root() {
+            anyhow::bail!("automatic upgrade requires root privileges");
+        }
+    } else if !super::service::is_root() {
+        // Check write permission to binary directory for manual upgrade mode.
+        let test_path = exe_dir.join(".aether-proxy.write-test");
+        match std::fs::File::create(&test_path) {
+            Ok(_) => {
+                let _ = std::fs::remove_file(&test_path);
+            }
+            Err(_) => {
+                anyhow::bail!(
+                    "no write access to {}. Use: sudo aether-proxy upgrade",
+                    exe_dir.display()
+                );
+            }
+        }
+    }
+
+    let platform = detect_platform();
+    eprintln!("  Platform: {}", platform);
+    eprintln!("  Current version: {}", CURRENT_VERSION);
+
+    let client = build_github_client()?;
+    let release = fetch_release(&client, version).await?;
+    let target_tag = &release.tag_name;
+    let target_semver = target_tag.strip_prefix("proxy-v").unwrap_or(target_tag);
+
+    eprintln!("  Target version: {} ({})", target_tag, release.name);
+
+    if target_semver == CURRENT_VERSION {
+        eprintln!(
+            "  Already running version {}, nothing to do.",
+            CURRENT_VERSION
+        );
+        return Ok(());
+    }
+
+    eprintln!();
+    eprintln!("  Upgrading: {} -> {}", CURRENT_VERSION, target_semver);
+    eprintln!();
+
+    if let Err(e) = download_and_verify(&client, target_tag, platform, &temp_path).await {
+        let _ = std::fs::remove_file(&temp_path);
+        return Err(e);
+    }
+    let backup_path = match atomic_replace(&temp_path) {
+        Ok(backup) => backup,
+        Err(e) => {
+            let _ = std::fs::remove_file(&temp_path);
+            return Err(e);
+        }
+    };
+
+    match restart_mode {
+        RestartMode::BestEffort => {
+            // Restart systemd service if running.
+            // Use best-effort: binary is already replaced, so a restart failure should
+            // not abort the whole upgrade -- the user can restart manually.
+            if super::service::is_service_active() {
+                if super::service::is_root() {
+                    eprintln!("  Restarting systemd service...");
+                    match super::service::run_cmd("systemctl", &["restart", "aether-proxy"]) {
+                        Ok(()) => eprintln!("  Service restarted."),
+                        Err(e) => {
+                            eprintln!("  WARNING: failed to restart service: {}", e);
+                            eprintln!("  Run manually: sudo systemctl restart aether-proxy");
+                        }
+                    }
+                } else {
+                    eprintln!("  Systemd service is active, but restart requires root.");
+                    eprintln!("  Run: sudo systemctl restart aether-proxy");
+                    eprintln!("  Skipping restart.");
+                }
+            } else {
+                eprintln!("  No active systemd service detected, skipping restart.");
+            }
+        }
+        RestartMode::Required => {
+            if !super::service::is_root() {
+                anyhow::bail!("automatic upgrade requires root privileges");
+            }
+            eprintln!("  Restarting systemd service...");
+            super::service::run_cmd("systemctl", &["restart", "aether-proxy"])?;
+            eprintln!("  Service restarted.");
+        }
+    }
+
+    eprintln!();
+    eprintln!("  Upgrade complete!");
+    eprintln!(
+        "  Backup kept at: {} (will be cleaned up on next upgrade)",
+        backup_path.display()
+    );
+    Ok(())
+}
+
+/// `aether-proxy upgrade [version]` -- self-upgrade from GitHub releases.
+pub async fn cmd_upgrade(version: Option<String>) -> anyhow::Result<()> {
+    execute_upgrade(version.as_deref(), false, RestartMode::BestEffort).await
+}
+
+/// Perform automatic upgrade to a specific version.
+///
+/// This path is designed for server-pushed upgrades in systemd/root scenarios:
+/// it requires root and requires a successful `systemctl restart aether-proxy`.
+pub async fn perform_upgrade(version: &str) -> anyhow::Result<()> {
+    execute_upgrade(Some(version), true, RestartMode::Required).await
+}