From e6add00f0dc706c2d894278f659d5c97cf62904e Mon Sep 17 00:00:00 2001 From: Brian Krabach Date: Mon, 30 Mar 2026 07:39:18 -0700 Subject: [PATCH 01/15] feat: loading placeholder tile while new session is being created - Inject .tile--loading skeleton tile into #session-grid immediately after POST /api/sessions succeeds, giving instant visual feedback while the backend creates the tmux session (which may take several seconds) - Remove the placeholder when the poll finds the session or on timeout - Add shimmer animation via @keyframes shimmer to style.css - Tile placed after original .tile-body pre rule to avoid selector-substring match in _extract_rule_block CSS tests --- muxplex/frontend/app.js | 49 ++++++++++--- muxplex/frontend/style.css | 24 ++++++ muxplex/frontend/terminal.js | 20 +++++ muxplex/frontend/tests/test_app.mjs | 93 +++++++++++++++++++++++- muxplex/frontend/tests/test_terminal.mjs | 24 ++++++ 5 files changed, 195 insertions(+), 15 deletions(-) diff --git a/muxplex/frontend/app.js b/muxplex/frontend/app.js index 44fa0ed..771bdbf 100644 --- a/muxplex/frontend/app.js +++ b/muxplex/frontend/app.js @@ -195,8 +195,8 @@ function trackInteraction() { // ─── State restoration ─────────────────────────────────────────────────────── /** * Restore application state from the server on page load. - * Calls GET /api/state and, if an active session exists, re-opens it - * without POSTing to /connect (ttyd is already running). + * Calls GET /api/state and, if an active session exists, re-opens it, + * skipping only the zoom animation (ttyd is re-spawned to handle service restarts). * Always resolves — errors are logged as warnings so the app can start normally. * @returns {Promise} */ @@ -205,7 +205,7 @@ async function restoreState() { const res = await api('GET', '/api/state'); const state = await res.json(); if (state.active_session) { - await openSession(state.active_session, { skipConnect: true }); + await openSession(state.active_session, { skipAnimation: true }); } } catch (err) { console.warn('[restoreState] could not restore previous session:', err); @@ -821,7 +821,7 @@ function updatePillBell() { * Open a session in fullscreen view with a zoom transition. * @param {string} name - session name * @param {object} [opts] - * @param {boolean} [opts.skipConnect] - if true, skip the /connect POST (ttyd already running) + * @param {boolean} [opts.skipAnimation] - if true, skip the zoom animation (e.g. on page restore) * @returns {Promise} */ async function openSession(name, opts = {}) { @@ -838,7 +838,8 @@ async function openSession(name, opts = {}) { if (nameEl) nameEl.textContent = name; // Zoom animation: pin tile at current position, then animate to full viewport - const tile = document.querySelector(`[data-session="${name}"]`); + // Skipped on restore (skipAnimation:true) — no tile DOM element to zoom from + const tile = opts.skipAnimation ? null : document.querySelector(`[data-session="${name}"]`); if (tile) { const rect = tile.getBoundingClientRect(); tile.style.position = 'fixed'; @@ -870,7 +871,7 @@ async function openSession(name, opts = {}) { initSidebar(); renderSidebar(_currentSessions, name); resolve(); - }, 260); + }, opts.skipAnimation ? 0 : 260); // If setTimeout is stubbed (e.g. in test env), resolve immediately so we don't hang if (timerId == null) resolve(); }); @@ -891,11 +892,9 @@ async function openSession(name, opts = {}) { const fab = $('new-session-fab'); if (fab) fab.classList.add('hidden'); - // Connect to session (kill old ttyd, spawn new one for this session) + // Always spawn ttyd for this session — ensures correct session after service restart or page restore try { - if (!opts.skipConnect) { - await api('POST', `/api/sessions/${name}/connect`); - } + await api('POST', `/api/sessions/${name}/connect`); } catch (err) { showToast(err.message || 'Connection failed'); return closeSession(); @@ -1015,9 +1014,14 @@ function saveDisplaySettings(settings) { * @param {object} ds - display settings object */ function applyDisplaySettings(ds) { - // Apply font size as CSS custom property + // Apply font size as CSS custom property (tile previews) document.documentElement.style.setProperty('--preview-font-size', ds.fontSize + 'px'); + // Apply font size to the live xterm.js terminal without reconnecting + if (window._setTerminalFontSize) { + window._setTerminalFontSize(ds.fontSize); + } + // Apply grid columns var grid = document.getElementById('session-grid'); if (grid) { @@ -1418,10 +1422,30 @@ async function createNewSession(name) { const sessionName = data.name || name; showToast('Creating session \'' + sessionName + '\'…'); + // Inject a loading placeholder tile so the user sees feedback immediately + var loadingTile = null; + var grid = document.getElementById('session-grid'); + if (grid) { + loadingTile = document.createElement('div'); + loadingTile.className = 'session-tile tile--loading'; + loadingTile.id = 'loading-tile-' + sessionName; + loadingTile.innerHTML = + '
' + escapeHtml(sessionName) + '' + + 'Creating...
' + + '
';
+      grid.appendChild(loadingTile);
+    }
+
+    function removeLoadingTile() {
+      var tile = document.getElementById('loading-tile-' + sessionName);
+      if (tile) tile.remove();
+    }
+
     const ss = _serverSettings || {};
     if (ss.auto_open_created === false) {
       // Auto-open disabled — just do one refresh
       await pollSessions();
+      removeLoadingTile();
       return;
     }
 
@@ -1436,10 +1460,12 @@ async function createNewSession(name) {
       });
       if (found) {
         clearInterval(pollForSession);
+        removeLoadingTile();
         showToast('Session \'' + sessionName + '\' ready');
         openSession(sessionName);
       } else if (attempts >= maxAttempts) {
         clearInterval(pollForSession);
+        removeLoadingTile();
         showToast('Session \'' + sessionName + '\' is taking longer than expected');
       }
     }, 2000);
@@ -1647,7 +1673,6 @@ document.addEventListener('DOMContentLoaded', () => {
       startPolling();
       loadServerSettings();
       startHeartbeat();
-      requestNotificationPermission();
       bindStaticEventListeners();
     })
     .catch((err) => {
diff --git a/muxplex/frontend/style.css b/muxplex/frontend/style.css
index c240f09..69666ef 100644
--- a/muxplex/frontend/style.css
+++ b/muxplex/frontend/style.css
@@ -239,6 +239,30 @@ body {
   margin: 0;
 }
 
+/* Loading placeholder tile — shown while a new session is being created */
+.tile--loading {
+  opacity: 0.6;
+  pointer-events: none;
+}
+
+.tile--loading .tile-body pre {
+  background: repeating-linear-gradient(
+    90deg,
+    var(--border) 0px,
+    var(--bg-surface) 30px,
+    var(--border) 60px
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s ease-in-out infinite;
+  min-height: 60px;
+  border-radius: 2px;
+}
+
+@keyframes shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+
 .tile-pre {
   position: absolute;
   inset: 0;
diff --git a/muxplex/frontend/terminal.js b/muxplex/frontend/terminal.js
index 78d2159..c328fbb 100644
--- a/muxplex/frontend/terminal.js
+++ b/muxplex/frontend/terminal.js
@@ -258,6 +258,26 @@ function closeTerminal() {
 window._openTerminal = openTerminal;
 window._closeTerminal = closeTerminal;
 
+// ---------------------------------------------------------------------------
+// setTerminalFontSize — live font-size update without reconnecting
+// ---------------------------------------------------------------------------
+
+/**
+ * Update the terminal font size at runtime without reconnecting.
+ * Modifies _term.options.fontSize and refits the terminal to recalculate dimensions.
+ * No-op when no terminal is open.
+ * @param {number} size - font size in pixels
+ */
+function setTerminalFontSize(size) {
+  if (!_term) return;
+  _term.options.fontSize = size;
+  if (_fitAddon) {
+    try { _fitAddon.fit(); } catch (_) {}
+  }
+}
+
+window._setTerminalFontSize = setTerminalFontSize;
+
 // ---------------------------------------------------------------------------
 // Android touch scroll — rAF-batched WheelEvent dispatch
 // Android batches touchmove events irregularly; dispatching one WheelEvent
diff --git a/muxplex/frontend/tests/test_app.mjs b/muxplex/frontend/tests/test_app.mjs
index de0d8a2..f0dc75f 100644
--- a/muxplex/frontend/tests/test_app.mjs
+++ b/muxplex/frontend/tests/test_app.mjs
@@ -897,20 +897,24 @@ test('openSession returns a Promise', () => {
   globalThis.setTimeout = origSetTimeout;
 });
 
-test('openSession with skipConnect calls window._openTerminal inside setTimeout callback', async () => {
+test('openSession with skipAnimation calls window._openTerminal after connect POST', async () => {
+  // After the fix: skipAnimation only skips the zoom animation, connect always fires.
   let openTerminalCalledWith = null;
+  const origFetch = globalThis.fetch;
   const origGetById = globalThis.document.getElementById;
   const origQS = globalThis.document.querySelector;
   const origSetTimeout = globalThis.setTimeout;
+  globalThis.fetch = async (url, opts) => ({ ok: true });
   globalThis.document.getElementById = () => ({ textContent: '', style: {}, classList: { remove: () => {}, add: () => {} } });
   globalThis.document.querySelector = () => null;
-  // Use a synchronous mock so setTimeout callbacks run immediately — _openTerminal is now called inside setTimeout
+  // Use a synchronous mock so setTimeout callbacks run immediately
   globalThis.setTimeout = (fn) => { fn(); };
   globalThis.window._openTerminal = (name) => { openTerminalCalledWith = name; };
 
-  await app.openSession('my-session', { skipConnect: true });
+  await app.openSession('my-session', { skipAnimation: true });
 
   assert.strictEqual(openTerminalCalledWith, 'my-session', '_openTerminal should be called with session name');
+  globalThis.fetch = origFetch;
   globalThis.document.getElementById = origGetById;
   globalThis.document.querySelector = origQS;
   globalThis.setTimeout = origSetTimeout;
@@ -1952,4 +1956,87 @@ test('createNewSession polls for session before auto-opening (not immediate setT
   );
 });
 
+// --- Issue 1: Loading placeholder tile ---
+
+test('createNewSession injects tile--loading placeholder after POST succeeds', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  const start = source.indexOf('async function createNewSession(');
+  assert.ok(start !== -1, 'createNewSession must exist');
+  const snippet = source.slice(start, start + 2500);
+  assert.ok(snippet.includes('tile--loading'), 'createNewSession must inject tile--loading placeholder class');
+  assert.ok(snippet.includes('loading-tile-'), 'createNewSession must use loading-tile- id prefix for the placeholder');
+});
+
+test('createNewSession removes loading placeholder when session is found', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  const start = source.indexOf('async function createNewSession(');
+  const snippet = source.slice(start, start + 2500);
+  assert.ok(
+    snippet.includes('loadingTile') && snippet.includes('.remove()'),
+    'createNewSession must remove the loading tile (loadingTile.remove()) when session is found'
+  );
+});
+
+test('CSS style.css has tile--loading and shimmer animation', () => {
+  const source = fs.readFileSync(new URL('../style.css', import.meta.url), 'utf8');
+  assert.ok(source.includes('tile--loading'), 'style.css must have .tile--loading rule');
+  assert.ok(source.includes('shimmer'), 'style.css must have shimmer animation');
+});
+
+// --- Issue 2: Always call connect on restore ---
+
+test('openSession always POSTs to connect even when skipConnect option is passed', async () => {
+  // Before the fix, skipConnect:true skipped the connect POST entirely.
+  // After the fix, connect is always called; the option is renamed to skipAnimation.
+  const fetchCalls = [];
+  const origFetch = globalThis.fetch;
+  const origGetById = globalThis.document.getElementById;
+  const origQS = globalThis.document.querySelector;
+  const origSetTimeout = globalThis.setTimeout;
+  globalThis.fetch = async (url, opts) => { fetchCalls.push({ url, opts }); return { ok: true }; };
+  globalThis.document.getElementById = () => ({ textContent: '', style: {}, classList: { remove: () => {}, add: () => {} } });
+  globalThis.document.querySelector = () => null;
+  globalThis.setTimeout = () => {};
+  globalThis.window._openTerminal = () => {};
+
+  await app.openSession('work', { skipConnect: true });
+
+  const connectCall = fetchCalls.find((c) => c.url === '/api/sessions/work/connect');
+  assert.ok(connectCall, 'skipConnect:true must NOT prevent connect POST — connect always fires after fix');
+  assert.strictEqual(connectCall.opts.method, 'POST');
+  globalThis.fetch = origFetch;
+  globalThis.document.getElementById = origGetById;
+  globalThis.document.querySelector = origQS;
+  globalThis.setTimeout = origSetTimeout;
+});
+
+// --- Issue 3: Notification permission on user click only ---
+
+test('DOMContentLoaded handler does NOT call requestNotificationPermission at startup', () => {
+  // Browsers require notification permission to be requested in response to a user gesture.
+  // Auto-calling at startup is silently blocked, leaving the permission in a broken state.
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  const domContentLoadedIdx = source.indexOf("document.addEventListener('DOMContentLoaded'");
+  assert.ok(domContentLoadedIdx !== -1, 'DOMContentLoaded handler must exist');
+  // Extract the DOMContentLoaded handler body (next ~600 chars covers the entire handler)
+  const handlerBody = source.substring(domContentLoadedIdx, domContentLoadedIdx + 600);
+  assert.ok(
+    !handlerBody.includes('requestNotificationPermission'),
+    'requestNotificationPermission must NOT be called automatically in DOMContentLoaded — only on user click'
+  );
+});
+
+// --- Issue 4: Apply font size to live terminal without reconnecting ---
+
+test('applyDisplaySettings calls window._setTerminalFontSize when available', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  const fnStart = source.indexOf('function applyDisplaySettings(');
+  assert.ok(fnStart !== -1, 'applyDisplaySettings must exist');
+  const fnBody = source.substring(fnStart, fnStart + 600);
+  assert.ok(
+    fnBody.includes('_setTerminalFontSize'),
+    'applyDisplaySettings must call window._setTerminalFontSize to update live terminal font size'
+  );
+});
+
 
diff --git a/muxplex/frontend/tests/test_terminal.mjs b/muxplex/frontend/tests/test_terminal.mjs
index d467737..3bf05a3 100644
--- a/muxplex/frontend/tests/test_terminal.mjs
+++ b/muxplex/frontend/tests/test_terminal.mjs
@@ -733,4 +733,28 @@ test('terminal.js Android touch scroll is UA-gated', () => {
   assert.ok(!source.includes('scrollLines'), 'must NOT use scrollLines (scrolls local buffer not PTY)');
 });
 
+// --- Issue 4: setTerminalFontSize ---
+
+test('terminal.js exposes window._setTerminalFontSize function', () => {
+  const source = fs.readFileSync(new URL('../terminal.js', import.meta.url), 'utf8');
+  assert.ok(
+    source.includes('window._setTerminalFontSize'),
+    'terminal.js must expose window._setTerminalFontSize for live font size updates'
+  );
+});
+
+test('_setTerminalFontSize sets _term.options.fontSize and calls _fitAddon.fit()', () => {
+  const source = fs.readFileSync(new URL('../terminal.js', import.meta.url), 'utf8');
+  // The function body must update _term.options.fontSize
+  assert.ok(
+    source.includes('_term.options.fontSize = size'),
+    '_setTerminalFontSize must assign _term.options.fontSize = size'
+  );
+  // And call _fitAddon.fit()
+  assert.ok(
+    source.includes('_fitAddon.fit()'),
+    '_setTerminalFontSize must call _fitAddon.fit() to reflow the terminal'
+  );
+});
+
 

From df3e252f73b7b983622739d1fea5077e1044e9d0 Mon Sep 17 00:00:00 2001
From: Brian Krabach 
Date: Mon, 30 Mar 2026 08:03:49 -0700
Subject: [PATCH 02/15] =?UTF-8?q?fix:=20exempt=20static=20assets=20from=20?=
 =?UTF-8?q?auth=20middleware=20=E2=80=94=20login=20page=20can=20load=20CSS?=
 =?UTF-8?q?/JS/images?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 muxplex/auth.py           | 25 +++++++++++++++--
 muxplex/tests/test_api.py | 59 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 3 deletions(-)

diff --git a/muxplex/auth.py b/muxplex/auth.py
index a7535e5..f2937f6 100644
--- a/muxplex/auth.py
+++ b/muxplex/auth.py
@@ -136,6 +136,20 @@ def authenticate_pam(username: str, password: str) -> bool:
 # Paths that bypass auth (login page itself, static assets it needs)
 _AUTH_EXEMPT_PATHS = {"/login", "/auth/mode", "/auth/logout"}
 
+# File extensions that are always served without auth — the login page needs
+# its own CSS, JS, images, and fonts before the user has a session cookie.
+_STATIC_EXTENSIONS = {
+    ".css",
+    ".js",
+    ".svg",
+    ".png",
+    ".ico",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".map",
+}
+
 # Socket-level localhost addresses — cannot be forged via HTTP headers
 _LOCALHOST_ADDRS = {"127.0.0.1", "::1"}
 
@@ -168,12 +182,17 @@ class AuthMiddleware(BaseHTTPMiddleware):
         if request.url.path in _AUTH_EXEMPT_PATHS:
             return await call_next(request)
 
-        # 3. Valid session cookie
+        # 3. Static assets — login page needs its CSS/JS/images before auth
+        path = request.url.path
+        if any(path.endswith(ext) for ext in _STATIC_EXTENSIONS):
+            return await call_next(request)
+
+        # 4. Valid session cookie
         cookie = request.cookies.get("muxplex_session")
         if cookie and verify_session_cookie(self.secret, cookie, self.ttl_seconds):
             return await call_next(request)
 
-        # 4. Authorization: Basic header
+        # 5. Authorization: Basic header
         auth_header = request.headers.get("authorization", "")
         if auth_header.lower().startswith("basic "):
             try:
@@ -186,7 +205,7 @@ class AuthMiddleware(BaseHTTPMiddleware):
                 pass
             return JSONResponse({"detail": "Invalid credentials"}, status_code=401)
 
-        # 5. No auth — redirect browsers, 401 for API clients
+        # 6. No auth — redirect browsers, 401 for API clients
         accept = request.headers.get("accept", "")
         if "application/json" in accept:
             return JSONResponse({"detail": "Authentication required"}, status_code=401)
diff --git a/muxplex/tests/test_api.py b/muxplex/tests/test_api.py
index e8fd7af..c12f67c 100644
--- a/muxplex/tests/test_api.py
+++ b/muxplex/tests/test_api.py
@@ -1066,3 +1066,62 @@ def test_delete_session_not_found(client, monkeypatch):
 
     response = client.delete("/api/sessions/nonexistent")
     assert response.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Issue 1: Static assets exempt from auth middleware
+# ---------------------------------------------------------------------------
+
+
+def test_static_asset_accessible_from_non_localhost_without_auth(monkeypatch):
+    """Static assets (.svg, .css, .js etc.) are served without auth from non-localhost.
+
+    The login page needs its own CSS/JS/images to render before the user has
+    authenticated. The auth middleware must exempt static file extensions.
+    """
+    monkeypatch.setenv("MUXPLEX_PASSWORD", "test-pw")
+    with TestClient(app, base_url="http://192.168.1.1", follow_redirects=False) as c:
+        response = c.get("/wordmark-on-dark.svg")
+    assert response.status_code == 200, (
+        f"Expected 200 for static asset from non-localhost, got {response.status_code}"
+    )
+
+
+def test_css_asset_accessible_from_non_localhost_without_auth(monkeypatch):
+    """CSS files are served without auth from non-localhost."""
+    monkeypatch.setenv("MUXPLEX_PASSWORD", "test-pw")
+    with TestClient(app, base_url="http://192.168.1.1", follow_redirects=False) as c:
+        response = c.get("/style.css")
+    assert response.status_code == 200, (
+        f"Expected 200 for CSS from non-localhost, got {response.status_code}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Issue 2: Hostname in page title
+# ---------------------------------------------------------------------------
+
+
+def test_index_page_title_contains_hostname(client):
+    """GET / returns HTML with hostname in page title (e.g. 'myhost — muxplex')."""
+    import socket
+
+    hostname = socket.gethostname().split(".")[0]
+    response = client.get("/")
+    assert response.status_code == 200
+    assert hostname in response.text, (
+        f"Expected hostname '{hostname}' in title of index page"
+    )
+    assert "muxplex" in response.text
+
+
+def test_login_page_title_contains_hostname(client):
+    """GET /login returns HTML with hostname in page title (e.g. 'Sign in — myhost — muxplex')."""
+    import socket
+
+    hostname = socket.gethostname().split(".")[0]
+    response = client.get("/login")
+    assert response.status_code == 200
+    assert hostname in response.text, (
+        f"Expected hostname '{hostname}' in title of login page"
+    )

From 261a25e6df3c22191721fdde8ea5efe84985361c Mon Sep 17 00:00:00 2001
From: Brian Krabach 
Date: Mon, 30 Mar 2026 08:05:14 -0700
Subject: [PATCH 03/15] =?UTF-8?q?feat:=20inject=20hostname=20into=20page?=
 =?UTF-8?q?=20title=20=E2=80=94=20visible=20in=20browser=20tabs=20across?=
 =?UTF-8?q?=20machines?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 muxplex/main.py | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/muxplex/main.py b/muxplex/main.py
index 7e30a70..505e27e 100644
--- a/muxplex/main.py
+++ b/muxplex/main.py
@@ -14,6 +14,7 @@ import logging
 import os
 import pathlib
 import pwd
+import socket
 import subprocess
 import sys
 import time
@@ -282,11 +283,15 @@ class CreateSessionPayload(BaseModel):
 
 
 # ---------------------------------------------------------------------------
-# Frontend directory
+# Frontend directory + hostname
 # ---------------------------------------------------------------------------
 
 _FRONTEND_DIR = pathlib.Path(__file__).parent / "frontend"
 
+# Short hostname (no domain) injected into page titles so browser tabs show
+# which machine each muxplex instance is running on.
+_HOSTNAME = socket.gethostname().split(".")[0]
+
 
 # ---------------------------------------------------------------------------
 # Routes
@@ -564,6 +569,18 @@ async def terminal_ws_proxy(websocket: WebSocket) -> None:
 # ---------------------------------------------------------------------------
 
 
+@app.get("/", response_class=HTMLResponse)
+@app.get("/index.html", response_class=HTMLResponse)
+async def index_page():
+    """Serve index.html with hostname injected into the page title."""
+    html = (_FRONTEND_DIR / "index.html").read_text()
+    html = html.replace(
+        "muxplex",
+        f"{_HOSTNAME} \u2014 muxplex",
+    )
+    return HTMLResponse(html)
+
+
 @app.get("/login", response_class=HTMLResponse)
 async def login_page():
     """Serve branded login.html with injected window.MUXPLEX_AUTH containing auth mode and username."""
@@ -573,6 +590,10 @@ async def login_page():
     html = html.replace(
         "", f""
     )
+    html = html.replace(
+        "Sign in \u2014 muxplex",
+        f"Sign in \u2014 {_HOSTNAME} \u2014 muxplex",
+    )
     return HTMLResponse(html)
 
 

From b448f120c528160216ff44cf8e217ae8db66a398 Mon Sep 17 00:00:00 2001
From: Brian Krabach 
Date: Mon, 30 Mar 2026 08:06:34 -0700
Subject: [PATCH 04/15] =?UTF-8?q?feat:=20dynamic=20favicon=20badge=20?=
 =?UTF-8?q?=E2=80=94=20amber=20dot=20overlay=20when=20sessions=20have=20un?=
 =?UTF-8?q?seen=20bells?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 muxplex/frontend/app.js             | 56 +++++++++++++++++++++++++++++
 muxplex/frontend/tests/test_app.mjs | 23 ++++++++++++
 2 files changed, 79 insertions(+)

diff --git a/muxplex/frontend/app.js b/muxplex/frontend/app.js
index 771bdbf..9acb4ca 100644
--- a/muxplex/frontend/app.js
+++ b/muxplex/frontend/app.js
@@ -248,6 +248,7 @@ async function pollSessions() {
     renderSidebar(sessions, _viewingSession);
     handleBellTransitions(prev, sessions);
     updateSessionPill(sessions);
+    updateFaviconBadge();
   } catch (err) {
     _pollFailCount++;
     setConnectionStatus(_pollFailCount <= 2 ? 'warn' : 'err');
@@ -815,6 +816,61 @@ function updatePillBell() {
   if (hasBell) el.classList.remove('hidden'); else el.classList.add('hidden');
 }
 
+// ---------------------------------------------------------------------------
+// Dynamic favicon — activity dot overlay
+// ---------------------------------------------------------------------------
+
+var _originalFavicon = null; // cached original favicon href
+
+/**
+ * Update the favicon with an activity dot if any session has unseen bells.
+ * Uses a 32x32 canvas to draw the original favicon + a colored circle overlay.
+ * Restores the original favicon when there are no unseen bells.
+ */
+function updateFaviconBadge() {
+  var hasActivity = _currentSessions && _currentSessions.some(function (s) {
+    return s.bell && s.bell.unseen_count > 0;
+  });
+
+  var link = document.querySelector('link[rel="icon"][sizes="32x32"]') ||
+             document.querySelector('link[rel="icon"]');
+  if (!link) return;
+
+  // Cache the original favicon on first call
+  if (!_originalFavicon) _originalFavicon = link.href;
+
+  if (!hasActivity) {
+    // Restore original favicon when no activity
+    if (link.href !== _originalFavicon) link.href = _originalFavicon;
+    return;
+  }
+
+  // Draw favicon + activity dot on canvas
+  var canvas = document.createElement('canvas');
+  canvas.width = 32;
+  canvas.height = 32;
+  var ctx = canvas.getContext('2d');
+  if (!ctx) return;
+
+  var img = new Image();
+  img.crossOrigin = 'anonymous';
+  img.onload = function () {
+    ctx.drawImage(img, 0, 0, 32, 32);
+
+    // Activity dot — brand amber (same as bell indicator)
+    ctx.beginPath();
+    ctx.arc(24, 8, 7, 0, 2 * Math.PI); // top-right area
+    ctx.fillStyle = '#F1A640';           // var(--bell-color)
+    ctx.fill();
+    ctx.strokeStyle = '#0D1117';         // var(--bg) — border for contrast
+    ctx.lineWidth = 2;
+    ctx.stroke();
+
+    link.href = canvas.toDataURL('image/png');
+  };
+  img.src = _originalFavicon;
+}
+
 // ─── Session open / close ────────────────────────────────────────────────────
 
 /**
diff --git a/muxplex/frontend/tests/test_app.mjs b/muxplex/frontend/tests/test_app.mjs
index f0dc75f..11918b5 100644
--- a/muxplex/frontend/tests/test_app.mjs
+++ b/muxplex/frontend/tests/test_app.mjs
@@ -2040,3 +2040,26 @@ test('applyDisplaySettings calls window._setTerminalFontSize when available', ()
 });
 
 
+
+// --- Issue: Dynamic favicon badge with activity dot ---
+
+test('updateFaviconBadge function exists in app.js', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  assert.ok(
+    source.includes('function updateFaviconBadge'),
+    'app.js must define updateFaviconBadge function'
+  );
+});
+
+test('pollSessions calls updateFaviconBadge', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  const pollStart = source.indexOf('async function pollSessions()');
+  assert.ok(pollStart !== -1, 'pollSessions must exist');
+  // Find the closing brace of pollSessions (next line starting with "}")
+  const pollEnd = source.indexOf('\n}', pollStart);
+  const pollBody = source.substring(pollStart, pollEnd + 2);
+  assert.ok(
+    pollBody.includes('updateFaviconBadge'),
+    'pollSessions must call updateFaviconBadge — update favicon on every poll cycle'
+  );
+});

From 85798783b648d236db22473e36cda81858408292 Mon Sep 17 00:00:00 2001
From: Brian Krabach 
Date: Mon, 30 Mar 2026 08:19:08 -0700
Subject: [PATCH 05/15] =?UTF-8?q?feat:=20add=20muxplex=20upgrade/update=20?=
 =?UTF-8?q?=E2=80=94=20stop=20service,=20reinstall,=20regenerate,=20restar?=
 =?UTF-8?q?t?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Platform-aware: launchctl on macOS, systemd on Linux/WSL.
Prefers uv tool install, falls back to pip.
Regenerates service file (picks up any plist/unit changes).
Runs doctor at the end for verification.
'update' is an alias for 'upgrade'.
---
 muxplex/cli.py            | 111 ++++++++++++++++++++++++++++++++++++++
 muxplex/tests/test_cli.py |  91 +++++++++++++++++++++++++++++++
 2 files changed, 202 insertions(+)

diff --git a/muxplex/cli.py b/muxplex/cli.py
index c7b8292..055093d 100644
--- a/muxplex/cli.py
+++ b/muxplex/cli.py
@@ -313,6 +313,110 @@ def install_service(*, system: bool = False) -> None:
         _install_systemd(executable, system=system)
 
 
+def upgrade() -> None:
+    """Upgrade muxplex to the latest version and restart the service."""
+    print("\nmuxplex upgrade\n")
+
+    # 1. Detect platform and stop service
+    if sys.platform == "darwin":
+        plist = Path.home() / "Library" / "LaunchAgents" / "com.muxplex.plist"
+        if plist.exists():
+            print("  Stopping launchd service...")
+            subprocess.run(["launchctl", "unload", str(plist)], capture_output=True)
+        else:
+            print("  No launchd service found (skipping stop)")
+    else:
+        # Linux/WSL — check systemd
+        result = subprocess.run(
+            ["systemctl", "--user", "is-active", "muxplex"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            print("  Stopping systemd service...")
+            subprocess.run(
+                ["systemctl", "--user", "stop", "muxplex"], capture_output=True
+            )
+        else:
+            print("  No active systemd service found (skipping stop)")
+
+    # 2. Reinstall via uv tool install
+    print("  Installing latest version...")
+    uv_path = shutil.which("uv")
+    if uv_path:
+        result = subprocess.run(
+            [
+                uv_path,
+                "tool",
+                "install",
+                "git+https://github.com/bkrabach/muxplex",
+                "--force",
+            ],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            print(f"  ERROR: uv tool install failed:\n{result.stderr}")
+            return
+        print("  Installed successfully")
+    else:
+        # Fallback: pip
+        pip_path = shutil.which("pip") or shutil.which("pip3")
+        if pip_path:
+            result = subprocess.run(
+                [
+                    pip_path,
+                    "install",
+                    "--upgrade",
+                    "git+https://github.com/bkrabach/muxplex",
+                ],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                print(f"  ERROR: pip install failed:\n{result.stderr}")
+                return
+            print("  Installed successfully")
+        else:
+            print("  ERROR: neither uv nor pip found — cannot upgrade")
+            return
+
+    # 3. Regenerate service file (picks up any plist/unit changes)
+    print("  Regenerating service file...")
+    install_service(system=False)
+
+    # 4. Restart service
+    if sys.platform == "darwin":
+        plist = Path.home() / "Library" / "LaunchAgents" / "com.muxplex.plist"
+        if plist.exists():
+            print("  Starting launchd service...")
+            subprocess.run(["launchctl", "load", str(plist)], capture_output=True)
+            print("  Service started")
+        else:
+            print("  Service file not found — run: muxplex install-service")
+    else:
+        result = subprocess.run(
+            ["systemctl", "--user", "is-enabled", "muxplex"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            print("  Restarting systemd service...")
+            subprocess.run(
+                ["systemctl", "--user", "daemon-reload"], capture_output=True
+            )
+            subprocess.run(
+                ["systemctl", "--user", "start", "muxplex"], capture_output=True
+            )
+            print("  Service started")
+        else:
+            print("  Service not enabled — run: muxplex install-service")
+
+    # 5. Doctor check
+    print("\n  Verifying...")
+    doctor()
+
+
 def main() -> None:
     """CLI entry point."""
     parser = argparse.ArgumentParser(
@@ -356,6 +460,11 @@ def main() -> None:
 
     sub.add_parser("doctor", help="Check dependencies and system status")
 
+    sub.add_parser(
+        "upgrade", help="Upgrade muxplex to latest version and restart service"
+    )
+    sub.add_parser("update", help="Alias for upgrade")
+
     args = parser.parse_args()
 
     if args.command == "install-service":
@@ -366,6 +475,8 @@ def main() -> None:
         reset_secret()
     elif args.command == "doctor":
         doctor()
+    elif args.command in ("upgrade", "update"):
+        upgrade()
     else:
         _check_dependencies()
         serve(
diff --git a/muxplex/tests/test_cli.py b/muxplex/tests/test_cli.py
index 8b620f3..ea81056 100644
--- a/muxplex/tests/test_cli.py
+++ b/muxplex/tests/test_cli.py
@@ -516,3 +516,94 @@ def test_main_dispatches_to_doctor(monkeypatch):
     assert len(calls) == 1, (
         "doctor() must be called once when 'doctor' subcommand is used"
     )
+
+
+# ---------------------------------------------------------------------------
+# upgrade / update subcommand tests
+# ---------------------------------------------------------------------------
+
+
+def test_upgrade_subcommand_registered():
+    """upgrade must be a valid subcommand."""
+    import io
+
+    from muxplex.cli import main
+
+    buf = io.StringIO()
+    with patch("sys.argv", ["muxplex", "--help"]):
+        try:
+            with patch("sys.stdout", buf):
+                main()
+        except SystemExit:
+            pass
+
+    help_text = buf.getvalue().lower()
+    assert "upgrade" in help_text
+
+
+def test_update_alias_registered():
+    """update must be a valid subcommand (alias for upgrade)."""
+    import io
+
+    from muxplex.cli import main
+
+    buf = io.StringIO()
+    with patch("sys.argv", ["muxplex", "--help"]):
+        try:
+            with patch("sys.stdout", buf):
+                main()
+        except SystemExit:
+            pass
+
+    help_text = buf.getvalue().lower()
+    assert "update" in help_text
+
+
+def test_upgrade_calls_uv_tool_install(monkeypatch, capsys):
+    """upgrade must attempt uv tool install."""
+    import subprocess
+
+    import muxplex.cli as cli_mod
+
+    calls = []
+
+    def mock_run(cmd, **kwargs):
+        calls.append(cmd)
+        return type("R", (), {"returncode": 0, "stdout": "", "stderr": ""})()
+
+    monkeypatch.setattr(subprocess, "run", mock_run)
+    monkeypatch.setattr(shutil, "which", lambda name: f"/usr/bin/{name}")
+    monkeypatch.setattr(cli_mod, "install_service", lambda system=False: None)
+    monkeypatch.setattr(cli_mod, "doctor", lambda: None)
+
+    cli_mod.upgrade()
+
+    # Should have called uv tool install
+    uv_calls = [c for c in calls if isinstance(c, list) and "uv" in str(c)]
+    assert len(uv_calls) > 0, "upgrade must call uv tool install"
+
+
+def test_main_dispatches_to_upgrade(monkeypatch):
+    """main() with 'upgrade' subcommand must invoke upgrade()."""
+    from muxplex.cli import main
+
+    calls = []
+    monkeypatch.setattr("muxplex.cli.upgrade", lambda: calls.append(True))
+
+    with patch("sys.argv", ["muxplex", "upgrade"]):
+        main()
+
+    assert len(calls) == 1, "upgrade() must be called once for 'upgrade' subcommand"
+
+
+def test_main_dispatches_update_to_upgrade(monkeypatch):
+    """main() with 'update' subcommand must also invoke upgrade()."""
+    from muxplex.cli import main
+
+    calls = []
+    monkeypatch.setattr("muxplex.cli.upgrade", lambda: calls.append(True))
+
+    with patch("sys.argv", ["muxplex", "update"]):
+        main()
+
+    assert len(calls) == 1, "upgrade() must be called once for 'update' subcommand"

From b53d1abbd2bea96d90317c2a83dac29d48dd626c Mon Sep 17 00:00:00 2001
From: Brian Krabach 
Date: Mon, 30 Mar 2026 08:33:24 -0700
Subject: [PATCH 06/15] feat: smart version check in upgrade + doctor

Detect install source via PEP 610 direct_url.json:
- git+https: compare installed commit sha vs git ls-remote HEAD
- PyPI: compare installed version vs pypi.org/pypi/muxplex/json
- editable: skip (user manages source directly)
- unknown: upgrade to be safe

upgrade() skips reinstall if already up to date. --force overrides.
doctor() shows install source, commit hash, and update availability.
---
 muxplex/cli.py            | 156 ++++++++++++++++++++++++++++++++++++--
 muxplex/tests/test_cli.py | 121 ++++++++++++++++++++++++++++-
 2 files changed, 268 insertions(+), 9 deletions(-)

diff --git a/muxplex/cli.py b/muxplex/cli.py
index 055093d..1d42842 100644
--- a/muxplex/cli.py
+++ b/muxplex/cli.py
@@ -21,6 +21,110 @@ from muxplex.auth import (
 _system_service_path = Path("/etc/systemd/system/muxplex.service")
 
 
+def _get_install_info() -> dict:
+    """Detect how muxplex was installed using PEP 610 direct_url.json.
+
+    Returns dict with keys:
+      source: 'git' | 'editable' | 'pypi' | 'unknown'
+      version: installed version string
+      commit: installed commit sha (git only)
+      url: git repo URL (git only)
+    """
+    import json
+    from importlib.metadata import PackageNotFoundError, distribution
+
+    info: dict = {
+        "source": "unknown",
+        "version": "0.0.0",
+        "commit": None,
+        "url": None,
+    }
+
+    try:
+        dist = distribution("muxplex")
+        info["version"] = dist.metadata["Version"]
+
+        du_text = dist.read_text("direct_url.json")
+        if du_text:
+            du = json.loads(du_text)
+
+            if "vcs_info" in du:
+                info["source"] = "git"
+                info["commit"] = du["vcs_info"].get("commit_id", "")
+                info["url"] = du.get("url", "")
+            elif "dir_info" in du and du["dir_info"].get("editable"):
+                info["source"] = "editable"
+            else:
+                info["source"] = "unknown"
+        else:
+            # No direct_url.json → probably PyPI
+            info["source"] = "pypi"
+    except PackageNotFoundError:
+        pass
+
+    return info
+
+
+def _check_for_update(info: dict) -> tuple[bool, str]:
+    """Check if an update is available. Returns (update_available, message).
+
+    For git: compares installed commit_id against remote HEAD sha.
+    For pypi: compares installed version against latest PyPI version.
+    For editable: always returns (False, "editable install").
+    For unknown: always returns (True, "unknown install source").
+    """
+    import json
+    import urllib.request
+
+    if info["source"] == "editable":
+        return False, "editable install — manage updates manually"
+
+    if info["source"] == "git":
+        try:
+            result = subprocess.run(
+                ["git", "ls-remote", info["url"], "HEAD"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode != 0:
+                return True, "could not check remote — upgrading to be safe"
+
+            remote_sha = (
+                result.stdout.strip().split()[0] if result.stdout.strip() else ""
+            )
+            local_sha = info["commit"] or ""
+
+            if not remote_sha:
+                return True, "could not read remote sha — upgrading to be safe"
+
+            if local_sha == remote_sha:
+                return False, f"up to date (commit {local_sha[:8]})"
+            else:
+                return True, f"update available ({local_sha[:8]} → {remote_sha[:8]})"
+        except Exception:
+            return True, "check failed — upgrading to be safe"
+
+    if info["source"] == "pypi":
+        try:
+            req = urllib.request.Request(
+                "https://pypi.org/pypi/muxplex/json",
+                headers={"Accept": "application/json"},
+            )
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                data = json.loads(resp.read())
+                latest = data["info"]["version"]
+                if latest == info["version"]:
+                    return False, f"up to date (v{info['version']})"
+                else:
+                    return True, f"update available (v{info['version']} → v{latest})"
+        except Exception:
+            return True, "could not check PyPI — upgrading to be safe"
+
+    # Unknown source
+    return True, "unknown install source — upgrading to be safe"
+
+
 def reset_secret() -> None:
     """Regenerate the signing secret and warn that all sessions are now invalid."""
     path = get_secret_path()
@@ -116,14 +220,26 @@ def doctor() -> None:
         else:
             print("    Install: sudo apt install ttyd")
 
-    # muxplex version
+    # muxplex version + install source + update check
     try:
         from importlib.metadata import version as pkg_version  # noqa: PLC0415
 
         muxplex_version = pkg_version("muxplex")
     except Exception:
         muxplex_version = "dev"
-    print(f"  {ok_mark} muxplex {muxplex_version}")
+
+    info = _get_install_info()
+    source_label = info["source"]
+    if info["commit"]:
+        source_label += f" @ {info['commit'][:8]}"
+    print(f"  {ok_mark} muxplex {muxplex_version} (installed via {source_label})")
+
+    update_available, update_msg = _check_for_update(info)
+    if update_available:
+        print(f"  {warn_mark} Update: {update_msg}")
+        print("    Run: muxplex upgrade")
+    else:
+        print(f"  {ok_mark} {update_msg}")
 
     # Settings file
     from muxplex.settings import SETTINGS_PATH  # noqa: PLC0415
@@ -313,10 +429,28 @@ def install_service(*, system: bool = False) -> None:
         _install_systemd(executable, system=system)
 
 
-def upgrade() -> None:
+def upgrade(*, force: bool = False) -> None:
     """Upgrade muxplex to the latest version and restart the service."""
     print("\nmuxplex upgrade\n")
 
+    # Show current install info
+    info = _get_install_info()
+    commit_suffix = f" (commit {info['commit'][:8]})" if info["commit"] else ""
+    print(f"  Installed: v{info['version']}{commit_suffix} via {info['source']}")
+
+    if not force:
+        update_available, message = _check_for_update(info)
+        print(f"  Status: {message}")
+
+        if not update_available:
+            print(
+                "\n  Already up to date."
+                " Use 'muxplex upgrade --force' to reinstall anyway.\n"
+            )
+            return
+    else:
+        print("  Status: --force specified — skipping version check")
+
     # 1. Detect platform and stop service
     if sys.platform == "darwin":
         plist = Path.home() / "Library" / "LaunchAgents" / "com.muxplex.plist"
@@ -460,10 +594,20 @@ def main() -> None:
 
     sub.add_parser("doctor", help="Check dependencies and system status")
 
-    sub.add_parser(
+    upgrade_parser = sub.add_parser(
         "upgrade", help="Upgrade muxplex to latest version and restart service"
     )
-    sub.add_parser("update", help="Alias for upgrade")
+    upgrade_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force reinstall even if already up to date",
+    )
+    update_parser = sub.add_parser("update", help="Alias for upgrade")
+    update_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force reinstall even if already up to date",
+    )
 
     args = parser.parse_args()
 
@@ -476,7 +620,7 @@ def main() -> None:
     elif args.command == "doctor":
         doctor()
     elif args.command in ("upgrade", "update"):
-        upgrade()
+        upgrade(force=getattr(args, "force", False))
     else:
         _check_dependencies()
         serve(
diff --git a/muxplex/tests/test_cli.py b/muxplex/tests/test_cli.py
index ea81056..3453fe6 100644
--- a/muxplex/tests/test_cli.py
+++ b/muxplex/tests/test_cli.py
@@ -560,7 +560,7 @@ def test_update_alias_registered():
 
 
 def test_upgrade_calls_uv_tool_install(monkeypatch, capsys):
-    """upgrade must attempt uv tool install."""
+    """upgrade must attempt uv tool install when update is available."""
     import subprocess
 
     import muxplex.cli as cli_mod
@@ -575,6 +575,12 @@ def test_upgrade_calls_uv_tool_install(monkeypatch, capsys):
     monkeypatch.setattr(shutil, "which", lambda name: f"/usr/bin/{name}")
     monkeypatch.setattr(cli_mod, "install_service", lambda system=False: None)
     monkeypatch.setattr(cli_mod, "doctor", lambda: None)
+    # Mock version check so upgrade proceeds regardless of local install type
+    monkeypatch.setattr(
+        cli_mod,
+        "_check_for_update",
+        lambda info: (True, "update available (abc12345 → def67890)"),
+    )
 
     cli_mod.upgrade()
 
@@ -588,7 +594,7 @@ def test_main_dispatches_to_upgrade(monkeypatch):
     from muxplex.cli import main
 
     calls = []
-    monkeypatch.setattr("muxplex.cli.upgrade", lambda: calls.append(True))
+    monkeypatch.setattr("muxplex.cli.upgrade", lambda force=False: calls.append(True))
 
     with patch("sys.argv", ["muxplex", "upgrade"]):
         main()
@@ -601,9 +607,118 @@ def test_main_dispatches_update_to_upgrade(monkeypatch):
     from muxplex.cli import main
 
     calls = []
-    monkeypatch.setattr("muxplex.cli.upgrade", lambda: calls.append(True))
+    monkeypatch.setattr("muxplex.cli.upgrade", lambda force=False: calls.append(True))
 
     with patch("sys.argv", ["muxplex", "update"]):
         main()
 
     assert len(calls) == 1, "upgrade() must be called once for 'update' subcommand"
+
+
+# ---------------------------------------------------------------------------
+# Smart version-check tests (_get_install_info / _check_for_update)
+# ---------------------------------------------------------------------------
+
+
+def test_get_install_info_returns_dict():
+    """_get_install_info must return a dict with all required keys."""
+    from muxplex.cli import _get_install_info
+
+    info = _get_install_info()
+    assert "source" in info
+    assert "version" in info
+    assert "commit" in info
+    assert "url" in info
+    assert info["source"] in ("git", "editable", "pypi", "unknown")
+
+
+def test_check_for_update_editable_returns_false():
+    """Editable installs must never suggest an update."""
+    from muxplex.cli import _check_for_update
+
+    info = {"source": "editable", "version": "0.1.0", "commit": None, "url": None}
+    available, msg = _check_for_update(info)
+    assert available is False
+    assert "editable" in msg
+
+
+def test_upgrade_force_skips_version_check(monkeypatch, capsys):
+    """upgrade(force=True) must skip the version check and proceed to install."""
+    import subprocess
+
+    import muxplex.cli as cli_mod
+
+    calls = []
+
+    def mock_run(cmd, **kwargs):
+        calls.append(cmd)
+        return type("R", (), {"returncode": 0, "stdout": "", "stderr": ""})()
+
+    monkeypatch.setattr(subprocess, "run", mock_run)
+    monkeypatch.setattr(shutil, "which", lambda name: f"/usr/bin/{name}")
+    monkeypatch.setattr(cli_mod, "install_service", lambda system=False: None)
+    monkeypatch.setattr(cli_mod, "doctor", lambda: None)
+    # With force=True the version check must be bypassed entirely
+    check_calls = []
+    monkeypatch.setattr(
+        cli_mod,
+        "_check_for_update",
+        lambda info: check_calls.append(info) or (True, "should not be reached"),
+    )
+
+    cli_mod.upgrade(force=True)
+
+    # _check_for_update must NOT have been called when force=True
+    assert len(check_calls) == 0, "Version check must be skipped when force=True"
+    # uv install must still be attempted
+    uv_calls = [c for c in calls if isinstance(c, list) and "uv" in str(c)]
+    assert len(uv_calls) > 0, "upgrade(force=True) must still call uv tool install"
+
+
+def test_upgrade_already_up_to_date_skips_install(monkeypatch, capsys):
+    """upgrade() must print 'up to date' and NOT call uv when version check says current."""
+    import subprocess
+
+    import muxplex.cli as cli_mod
+
+    calls = []
+
+    def mock_run(cmd, **kwargs):
+        calls.append(cmd)
+        return type("R", (), {"returncode": 0, "stdout": "", "stderr": ""})()
+
+    monkeypatch.setattr(subprocess, "run", mock_run)
+    monkeypatch.setattr(shutil, "which", lambda name: f"/usr/bin/{name}")
+    monkeypatch.setattr(cli_mod, "install_service", lambda system=False: None)
+    monkeypatch.setattr(cli_mod, "doctor", lambda: None)
+    monkeypatch.setattr(
+        cli_mod,
+        "_check_for_update",
+        lambda info: (False, "up to date (commit abcd1234)"),
+    )
+
+    cli_mod.upgrade()
+
+    out = capsys.readouterr().out
+    assert "up to date" in out.lower() or "already" in out.lower()
+    # uv install must NOT have been called
+    uv_calls = [c for c in calls if isinstance(c, list) and "uv" in str(c)]
+    assert len(uv_calls) == 0, "uv must NOT be called when already up to date"
+
+
+def test_upgrade_force_flag_registered():
+    """upgrade --force must be accepted by argparse without error."""
+    import io
+
+    from muxplex.cli import main
+
+    buf = io.StringIO()
+    with patch("sys.argv", ["muxplex", "upgrade", "--help"]):
+        try:
+            with patch("sys.stdout", buf):
+                main()
+        except SystemExit:
+            pass
+
+    help_text = buf.getvalue()
+    assert "--force" in help_text

From 320c9f3ba71863a7f419b3ff7f796577174909d0 Mon Sep 17 00:00:00 2001
From: Brian Krabach 
Date: Mon, 30 Mar 2026 08:52:43 -0700
Subject: [PATCH 07/15] =?UTF-8?q?fix:=20macOS=20launchd=20service=20?=
 =?UTF-8?q?=E2=80=94=20modern=20bootstrap=20API,=20auto-start,=20--host=20?=
 =?UTF-8?q?0.0.0.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace deprecated launchctl load/unload with bootstrap/bootout (modern
macOS API). Auto-bootout existing service before reinstall (fixes 'I/O
error' on reload). Add --host 0.0.0.0 to plist ProgramArguments so the
service is actually accessible from the network. install-service now
auto-starts the service and prints management commands. upgrade() also
uses modern API. doctor() checks if service is actually running.
---
 muxplex/cli.py            | 86 +++++++++++++++++++++++++++++++++------
 muxplex/tests/test_cli.py | 70 +++++++++++++++++++++++++++++++
 2 files changed, 144 insertions(+), 12 deletions(-)

diff --git a/muxplex/cli.py b/muxplex/cli.py
index 1d42842..8d49712 100644
--- a/muxplex/cli.py
+++ b/muxplex/cli.py
@@ -287,7 +287,18 @@ def doctor() -> None:
     if sys.platform == "darwin":
         plist = Path.home() / "Library" / "LaunchAgents" / "com.muxplex.plist"
         if plist.exists():
-            print(f"  {ok_mark} Service: launchd agent installed ({plist})")
+            uid = os.getuid()
+            result = subprocess.run(
+                ["launchctl", "print", f"gui/{uid}/com.muxplex"],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                print(f"  {ok_mark} Service: launchd agent running")
+            else:
+                print(
+                    f"  {warn_mark} Service: launchd agent installed but not running ({plist})"
+                )
         else:
             print(
                 f"  {warn_mark} Service: not installed (run: muxplex install-service)"
@@ -336,21 +347,25 @@ def _install_launchd(executable: str) -> None:
     import shutil
 
     # Prefer the entry point script ('muxplex') so macOS shows the correct
-    # process name in Activity Monitor, launchctl list, and login items.
-    # Fall back to 'python -m muxplex' if the entry point isn't on PATH.
+    # process name in Activity Monitor and launchctl list.
     muxplex_bin = shutil.which("muxplex")
     if muxplex_bin:
         program_args = f"""    
         {muxplex_bin}
+        --host
+        0.0.0.0
     """
     else:
         program_args = f"""    
         {executable}
         -m
         muxplex
+        --host
+        0.0.0.0
     """
 
     label = "com.muxplex"
+    uid = os.getuid()
     plist = f"""
 
 
@@ -372,12 +387,44 @@ def _install_launchd(executable: str) -> None:
 """
     path = Path.home() / "Library" / "LaunchAgents" / f"{label}.plist"
     path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Unload existing service first (ignore errors if not loaded)
+    subprocess.run(
+        ["launchctl", "bootout", f"gui/{uid}/{label}"],
+        capture_output=True,
+    )
+
     path.write_text(plist)
     print(f"Launch agent written to {path}")
-    print("Enable with:")
-    print(f"  launchctl load {path}")
-    print("Disable with:")
-    print(f"  launchctl unload {path}")
+    print()
+
+    # Load the service using the modern bootstrap API
+    result = subprocess.run(
+        ["launchctl", "bootstrap", f"gui/{uid}", str(path)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        print(f"  Service started (launchctl bootstrap gui/{uid})")
+    else:
+        # Fallback to legacy load for older macOS
+        result2 = subprocess.run(
+            ["launchctl", "load", str(path)],
+            capture_output=True,
+            text=True,
+        )
+        if result2.returncode == 0:
+            print("  Service started (launchctl load)")
+        else:
+            print("  Could not auto-start. Try manually:")
+            print(f"    launchctl bootstrap gui/{uid} {path}")
+
+    print()
+    print("Management commands:")
+    print(f"  Stop:    launchctl bootout gui/{uid}/{label}")
+    print(f"  Start:   launchctl bootstrap gui/{uid} {path}")
+    print(f"  Status:  launchctl print gui/{uid}/{label}")
+    print("  Logs:    tail -f /tmp/muxplex.log")
 
 
 def _install_systemd(executable: str, *, system: bool = False) -> None:
@@ -453,10 +500,14 @@ def upgrade(*, force: bool = False) -> None:
 
     # 1. Detect platform and stop service
     if sys.platform == "darwin":
-        plist = Path.home() / "Library" / "LaunchAgents" / "com.muxplex.plist"
+        label = "com.muxplex"
+        uid = os.getuid()
+        plist = Path.home() / "Library" / "LaunchAgents" / f"{label}.plist"
         if plist.exists():
             print("  Stopping launchd service...")
-            subprocess.run(["launchctl", "unload", str(plist)], capture_output=True)
+            subprocess.run(
+                ["launchctl", "bootout", f"gui/{uid}/{label}"], capture_output=True
+            )
         else:
             print("  No launchd service found (skipping stop)")
     else:
@@ -521,11 +572,22 @@ def upgrade(*, force: bool = False) -> None:
 
     # 4. Restart service
     if sys.platform == "darwin":
-        plist = Path.home() / "Library" / "LaunchAgents" / "com.muxplex.plist"
+        label = "com.muxplex"
+        uid = os.getuid()
+        plist = Path.home() / "Library" / "LaunchAgents" / f"{label}.plist"
         if plist.exists():
             print("  Starting launchd service...")
-            subprocess.run(["launchctl", "load", str(plist)], capture_output=True)
-            print("  Service started")
+            result = subprocess.run(
+                ["launchctl", "bootstrap", f"gui/{uid}", str(plist)],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                print("  Service started")
+            else:
+                # Fallback to legacy load for older macOS
+                subprocess.run(["launchctl", "load", str(plist)], capture_output=True)
+                print("  Service started (legacy)")
         else:
             print("  Service file not found — run: muxplex install-service")
     else:
diff --git a/muxplex/tests/test_cli.py b/muxplex/tests/test_cli.py
index 3453fe6..3131fde 100644
--- a/muxplex/tests/test_cli.py
+++ b/muxplex/tests/test_cli.py
@@ -263,12 +263,18 @@ def test_reset_secret_prints_warning(tmp_path, monkeypatch, capsys):
 
 def test_install_service_writes_launchd_plist_on_macos(tmp_path, monkeypatch):
     """install_service() on macOS writes a launchd plist to ~/Library/LaunchAgents/."""
+    import subprocess
     from muxplex.cli import install_service
 
     fake_home = tmp_path / "home"
     fake_home.mkdir()
     monkeypatch.setattr(Path, "home", staticmethod(lambda: fake_home))
     monkeypatch.setattr("sys.platform", "darwin")
+    monkeypatch.setattr(
+        subprocess,
+        "run",
+        lambda *a, **kw: type("R", (), {"returncode": 0, "stdout": "", "stderr": ""})(),
+    )
 
     install_service(system=False)
 
@@ -283,12 +289,18 @@ def test_install_service_writes_launchd_plist_on_macos(tmp_path, monkeypatch):
 
 def test_install_service_does_not_write_systemd_on_macos(tmp_path, monkeypatch):
     """install_service() on macOS must NOT write a systemd unit file."""
+    import subprocess
     from muxplex.cli import install_service
 
     fake_home = tmp_path / "home"
     fake_home.mkdir()
     monkeypatch.setattr(Path, "home", staticmethod(lambda: fake_home))
     monkeypatch.setattr("sys.platform", "darwin")
+    monkeypatch.setattr(
+        subprocess,
+        "run",
+        lambda *a, **kw: type("R", (), {"returncode": 0, "stdout": "", "stderr": ""})(),
+    )
 
     install_service(system=False)
 
@@ -296,6 +308,64 @@ def test_install_service_does_not_write_systemd_on_macos(tmp_path, monkeypatch):
     assert not systemd_path.exists(), "No systemd unit file should be written on macOS"
 
 
+def test_install_service_uses_modern_launchctl_on_macos(tmp_path, monkeypatch, capsys):
+    """install-service on macOS must use launchctl bootstrap (not load)."""
+    import subprocess
+    from muxplex.cli import install_service
+
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: fake_home))
+    monkeypatch.setattr("sys.platform", "darwin")
+    monkeypatch.setattr(shutil, "which", lambda name: f"/usr/local/bin/{name}")
+
+    calls = []
+
+    def mock_run(cmd, **kwargs):
+        calls.append(cmd)
+        return type("R", (), {"returncode": 0, "stdout": "", "stderr": ""})()
+
+    monkeypatch.setattr(subprocess, "run", mock_run)
+
+    install_service(system=False)
+
+    launchctl_cmds = [c for c in calls if isinstance(c, list) and "launchctl" in str(c)]
+    assert any(
+        "bootout" in str(c) for c in launchctl_cmds
+    ), "must bootout old service before loading"
+    assert any(
+        "bootstrap" in str(c) for c in launchctl_cmds
+    ), "must use launchctl bootstrap (modern API)"
+    # Must NOT use deprecated load
+    assert not any(
+        c == ["launchctl", "load"] or (isinstance(c, list) and c[:2] == ["launchctl", "load"])
+        for c in launchctl_cmds
+    ), "must NOT use deprecated launchctl load"
+
+
+def test_install_service_plist_includes_host_flag(tmp_path, monkeypatch):
+    """The generated plist must include --host 0.0.0.0 for network access."""
+    import subprocess
+    from muxplex.cli import install_service
+
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: fake_home))
+    monkeypatch.setattr("sys.platform", "darwin")
+    monkeypatch.setattr(shutil, "which", lambda name: f"/usr/local/bin/{name}")
+    monkeypatch.setattr(
+        subprocess,
+        "run",
+        lambda *a, **kw: type("R", (), {"returncode": 0, "stdout": "", "stderr": ""})(),
+    )
+
+    install_service(system=False)
+
+    plist_path = fake_home / "Library" / "LaunchAgents" / "com.muxplex.plist"
+    content = plist_path.read_text()
+    assert "0.0.0.0" in content, "plist must bind to 0.0.0.0 for network access"
+
+
 def test_install_service_writes_systemd_on_linux(tmp_path, monkeypatch):
     """install_service() on Linux writes a systemd unit to ~/.config/systemd/user/."""
     from muxplex.cli import install_service

From 2a30e88feb1afdea9f863cc95be62b8747cdf166 Mon Sep 17 00:00:00 2001
From: Brian Krabach 
Date: Mon, 30 Mar 2026 16:39:02 -0700
Subject: [PATCH 08/15] fix: launchd plist includes PATH with Homebrew + user
 local bin

launchd agents run with minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin).
Homebrew binaries (tmux, ttyd) in /opt/homebrew/bin and uv tool installs
in ~/.local/bin were not found, causing _check_dependencies() to exit(1).
Plist now includes EnvironmentVariables with a PATH that covers both
Apple Silicon and Intel Homebrew locations + ~/.local/bin.
---
 muxplex/cli.py | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/muxplex/cli.py b/muxplex/cli.py
index 8d49712..140703a 100644
--- a/muxplex/cli.py
+++ b/muxplex/cli.py
@@ -364,6 +364,20 @@ def _install_launchd(executable: str) -> None:
         0.0.0.0
     """
 
+    # Build PATH that includes Homebrew and common tool locations.
+    # launchd agents run with a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin).
+    # Homebrew binaries (tmux, ttyd, uv, git) won't be found without this.
+    _homebrew_paths = [
+        "/opt/homebrew/bin",  # Apple Silicon Homebrew
+        "/usr/local/bin",  # Intel Homebrew + system extras
+        "/opt/homebrew/sbin",
+        "/usr/local/sbin",
+    ]
+    _user_local = str(Path.home() / ".local" / "bin")  # uv/pip tool installs
+    _extra = [_user_local] + _homebrew_paths
+    _base = "/usr/bin:/bin:/usr/sbin:/sbin"
+    _service_path = ":".join(_extra) + ":" + _base
+
     label = "com.muxplex"
     uid = os.getuid()
     plist = f"""
@@ -374,6 +388,11 @@ def _install_launchd(executable: str) -> None:
     {label}
     ProgramArguments
 {program_args}
+    EnvironmentVariables
+    
+        PATH
+        {_service_path}
+    
     RunAtLoad
     
     KeepAlive

From 79576bcbfee4fd5af8d1f2fee8f7fc66f607a3bd Mon Sep 17 00:00:00 2001
From: Brian Krabach 
Date: Mon, 30 Mar 2026 17:17:34 -0700
Subject: [PATCH 09/15] feat: customizable delete session command template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Symmetric with create template. Default: 'tmux kill-session -t {name}'.
Configurable in Settings → Commands tab (renamed from 'New Session').
DELETE /api/sessions/{name} reads template from settings, substitutes
{name}, runs synchronously via subprocess.run with 30s timeout.

Enables custom teardown workflows like:
  amplifier-dev ~/dev/{name} --destroy

Changes:
- settings.py: add delete_session_template to DEFAULT_SETTINGS
- main.py: DELETE endpoint uses subprocess.run + template instead of run_tmux
- index.html: add delete template textarea + reset btn; rename tab to Commands
- app.js: DELETE_SESSION_DEFAULT_TEMPLATE constant, openSettings loads it,
  bindStaticEventListeners wires input/reset; constant exported

Tests added:
- test_settings.py: 3 tests for default, load, and patch of delete_session_template
- test_api.py: 2 tests for custom/default template substitution via subprocess mock;
  update existing test_delete_session_calls_kill_session to match new implementation
- test_frontend_html.py: 5 tests for textarea, placeholder, rows, reset btn, tab label
- test_app.mjs: 5 tests for constant definition, value, and wiring in openSettings/bindStaticEventListeners
---
 muxplex/frontend/app.js             |  33 ++++++-
 muxplex/frontend/index.html         |   8 +-
 muxplex/frontend/tests/test_app.mjs |  55 +++++++++++
 muxplex/main.py                     |  33 ++++++-
 muxplex/settings.py                 |   1 +
 muxplex/tests/test_api.py           | 139 ++++++++++++++++++++++++++--
 muxplex/tests/test_frontend_html.py |  91 ++++++++++++++++++
 muxplex/tests/test_settings.py      |  42 +++++++++
 8 files changed, 383 insertions(+), 19 deletions(-)

diff --git a/muxplex/frontend/app.js b/muxplex/frontend/app.js
index 9acb4ca..ca51984 100644
--- a/muxplex/frontend/app.js
+++ b/muxplex/frontend/app.js
@@ -142,6 +142,7 @@ const DISPLAY_DEFAULTS = {
   notificationPermission: 'default',
 };
 const NEW_SESSION_DEFAULT_TEMPLATE = 'tmux new-session -d -s {name}';
+const DELETE_SESSION_DEFAULT_TEMPLATE = 'tmux kill-session -t {name}';
 
 // ─── DOM helpers ──────────────────────────────────────────────────────────────
 function $(id) {
@@ -1221,11 +1222,17 @@ function openSettings() {
       autoOpenEl.checked = ss && ss.auto_open !== undefined ? !!ss.auto_open : true;
     }
 
-    // New Session tab - populate template textarea
+    // Commands tab - populate create template textarea
     const templateEl = $('setting-template');
     if (templateEl) {
       templateEl.value = (ss && ss.new_session_template) || NEW_SESSION_DEFAULT_TEMPLATE;
     }
+
+    // Commands tab - populate delete template textarea
+    const deleteTemplateEl = $('setting-delete-template');
+    if (deleteTemplateEl) {
+      deleteTemplateEl.value = (ss && ss.delete_session_template) || DELETE_SESSION_DEFAULT_TEMPLATE;
+    }
   });
 }
 
@@ -1687,7 +1694,7 @@ function bindStaticEventListeners() {
     });
   });
 
-  // New Session tab — template textarea with 500ms debounce
+  // Commands tab — create template textarea with 500ms debounce
   var _templateDebounceTimer;
   on($('setting-template'), 'input', function() {
     clearTimeout(_templateDebounceTimer);
@@ -1697,12 +1704,29 @@ function bindStaticEventListeners() {
     }, 500);
   });
 
-  // New Session tab — reset button restores default template
+  // Commands tab — create template reset button restores default
   on($('setting-template-reset'), 'click', function() {
     var el = $('setting-template');
     if (el) el.value = NEW_SESSION_DEFAULT_TEMPLATE;
     patchServerSetting('new_session_template', NEW_SESSION_DEFAULT_TEMPLATE);
   });
+
+  // Commands tab — delete template textarea with 500ms debounce
+  var _deleteTemplateDebounceTimer;
+  on($('setting-delete-template'), 'input', function() {
+    clearTimeout(_deleteTemplateDebounceTimer);
+    var val = this.value;
+    _deleteTemplateDebounceTimer = setTimeout(function() {
+      patchServerSetting('delete_session_template', val);
+    }, 500);
+  });
+
+  // Commands tab — delete template reset button restores default
+  on($('setting-delete-template-reset'), 'click', function() {
+    var el = $('setting-delete-template');
+    if (el) el.value = DELETE_SESSION_DEFAULT_TEMPLATE;
+    patchServerSetting('delete_session_template', DELETE_SESSION_DEFAULT_TEMPLATE);
+  });
 }
 
 // ─── Test-only helpers ────────────────────────────────────────────────────────
@@ -1798,6 +1822,9 @@ if (typeof module !== 'undefined' && module.exports) {
     createNewSession,
     // Kill session
     killSession,
+    // Constants
+    NEW_SESSION_DEFAULT_TEMPLATE,
+    DELETE_SESSION_DEFAULT_TEMPLATE,
     // Test-only helpers
     _setCurrentSessions,
     _setViewMode,
diff --git a/muxplex/frontend/index.html b/muxplex/frontend/index.html
index 56ca3fb..b96b453 100644
--- a/muxplex/frontend/index.html
+++ b/muxplex/frontend/index.html
@@ -87,7 +87,7 @@
         
         
         
-        
+        
       
       

         

@@ -169,6 +169,12 @@
             {name} is replaced with the session name
             
           

+          

+            
+            
+            {name} is replaced with the session name
+            
+          

         

       
     
diff --git a/muxplex/frontend/tests/test_app.mjs b/muxplex/frontend/tests/test_app.mjs
index 11918b5..b1b8ead 100644
--- a/muxplex/frontend/tests/test_app.mjs
+++ b/muxplex/frontend/tests/test_app.mjs
@@ -2063,3 +2063,58 @@ test('pollSessions calls updateFaviconBadge', () => {
     'pollSessions must call updateFaviconBadge — update favicon on every poll cycle'
   );
 });
+
+
+// --- Delete session template (task: customizable delete command) ---
+
+test('app.js defines DELETE_SESSION_DEFAULT_TEMPLATE constant', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  assert.ok(
+    source.includes('DELETE_SESSION_DEFAULT_TEMPLATE'),
+    'app.js must define DELETE_SESSION_DEFAULT_TEMPLATE constant'
+  );
+});
+
+test('DELETE_SESSION_DEFAULT_TEMPLATE value is tmux kill-session -t {name}', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  assert.ok(
+    source.includes("'tmux kill-session -t {name}'") || source.includes('"tmux kill-session -t {name}"'),
+    "DELETE_SESSION_DEFAULT_TEMPLATE must be set to 'tmux kill-session -t {name}'"
+  );
+});
+
+test('openSettings loads delete_session_template from server settings', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  const fnStart = source.indexOf('function openSettings(');
+  assert.ok(fnStart !== -1, 'openSettings must exist');
+  const fnEnd = source.indexOf('\nfunction ', fnStart + 1);
+  const fnBody = source.substring(fnStart, fnEnd > fnStart ? fnEnd : fnStart + 3000);
+  assert.ok(
+    fnBody.includes('setting-delete-template'),
+    'openSettings must populate #setting-delete-template from server settings'
+  );
+});
+
+test('bindStaticEventListeners wires delete template input to save', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  const fnStart = source.indexOf('function bindStaticEventListeners(');
+  assert.ok(fnStart !== -1, 'bindStaticEventListeners must exist');
+  const fnEnd = source.indexOf('\nfunction ', fnStart + 1);
+  const fnBody = source.substring(fnStart, fnEnd > fnStart ? fnEnd : fnStart + 6000);
+  assert.ok(
+    fnBody.includes('setting-delete-template'),
+    'bindStaticEventListeners must wire #setting-delete-template input event to save'
+  );
+});
+
+test('bindStaticEventListeners wires delete template reset button', () => {
+  const source = fs.readFileSync(new URL('../app.js', import.meta.url), 'utf8');
+  const fnStart = source.indexOf('function bindStaticEventListeners(');
+  assert.ok(fnStart !== -1, 'bindStaticEventListeners must exist');
+  const fnEnd = source.indexOf('\nfunction ', fnStart + 1);
+  const fnBody = source.substring(fnStart, fnEnd > fnStart ? fnEnd : fnStart + 6000);
+  assert.ok(
+    fnBody.includes('setting-delete-template-reset'),
+    'bindStaticEventListeners must wire #setting-delete-template-reset click handler'
+  );
+});
diff --git a/muxplex/main.py b/muxplex/main.py
index 505e27e..61b36da 100644
--- a/muxplex/main.py
+++ b/muxplex/main.py
@@ -411,9 +411,13 @@ async def delete_current_session() -> dict:
 
 @app.delete("/api/sessions/{name}")
 async def delete_session(name: str) -> dict:
-    """Kill a tmux session by name.
+    """Kill/destroy a tmux session using the delete_session_template from settings.
 
-    Runs `tmux kill-session -t {name}`. Returns {ok: True, name: name}.
+    Reads delete_session_template, substitutes {name}, and runs it synchronously
+    (30s timeout) so the caller can rely on the session being gone on return.
+
+    Returns {ok: True, name: name}. Errors are logged as warnings — the endpoint
+    always returns 200 so the UI can refresh and reflect the gone session.
     404 if session is not in the known session list (when non-empty).
     Must be declared after DELETE /api/sessions/current so "current" routes correctly.
     """
@@ -421,10 +425,29 @@ async def delete_session(name: str) -> dict:
     if known and name not in known:
         raise HTTPException(status_code=404, detail=f"Session '{name}' not found")
 
+    settings = load_settings()
+    command = settings.get(
+        "delete_session_template", "tmux kill-session -t {name}"
+    ).replace("{name}", name)
+
     try:
-        await run_tmux("kill-session", "-t", name)
-    except RuntimeError:
-        raise HTTPException(status_code=500, detail=f"Failed to kill session '{name}'")
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            _log.warning(
+                "Delete command failed (rc=%d): %s",
+                result.returncode,
+                result.stderr.strip(),
+            )
+    except subprocess.TimeoutExpired:
+        _log.warning("Delete command timed out after 30s: %r", command)
+    except Exception:
+        _log.warning("Delete command failed: %r", command)
 
     return {"ok": True, "name": name}
 
diff --git a/muxplex/settings.py b/muxplex/settings.py
index 27ee91d..9336334 100644
--- a/muxplex/settings.py
+++ b/muxplex/settings.py
@@ -17,6 +17,7 @@ DEFAULT_SETTINGS: dict = {
     "window_size_largest": False,
     "auto_open_created": True,
     "new_session_template": "tmux new-session -d -s {name}",
+    "delete_session_template": "tmux kill-session -t {name}",
 }
 
 
diff --git a/muxplex/tests/test_api.py b/muxplex/tests/test_api.py
index c12f67c..3aaade0 100644
--- a/muxplex/tests/test_api.py
+++ b/muxplex/tests/test_api.py
@@ -1044,20 +1044,34 @@ def test_delete_session_success(client, monkeypatch):
 
 
 def test_delete_session_calls_kill_session(client, monkeypatch):
-    """DELETE /api/sessions/{name} calls tmux kill-session -t {name}."""
-    from unittest.mock import AsyncMock
+    """DELETE /api/sessions/{name} runs 'tmux kill-session -t {name}' via subprocess (default template)."""
+    from unittest.mock import MagicMock, patch
 
     monkeypatch.setattr("muxplex.main.get_session_list", lambda: ["my-session"])
-    mock_run_tmux = AsyncMock(return_value="")
-    monkeypatch.setattr("muxplex.main.run_tmux", mock_run_tmux)
 
-    client.delete("/api/sessions/my-session")
+    captured = []
 
-    assert mock_run_tmux.called
-    args = mock_run_tmux.call_args[0]
-    assert args[0] == "kill-session"
-    assert "-t" in args
-    assert "my-session" in args
+    def mock_run(cmd, **kwargs):
+        captured.append(cmd)
+        result = MagicMock()
+        result.returncode = 0
+        result.stderr = ""
+        return result
+
+    with patch("muxplex.main.subprocess.run", side_effect=mock_run):
+        client.delete("/api/sessions/my-session")
+
+    assert len(captured) == 1, "subprocess.run must be called exactly once"
+    executed_cmd = captured[0]
+    assert "kill-session" in executed_cmd, (
+        f"Default command must include 'kill-session', got: {executed_cmd!r}"
+    )
+    assert "-t" in executed_cmd, (
+        f"Default command must include '-t', got: {executed_cmd!r}"
+    )
+    assert "my-session" in executed_cmd, (
+        f"Command must include session name 'my-session', got: {executed_cmd!r}"
+    )
 
 
 def test_delete_session_not_found(client, monkeypatch):
@@ -1125,3 +1139,108 @@ def test_login_page_title_contains_hostname(client):
     assert hostname in response.text, (
         f"Expected hostname '{hostname}' in title of login page"
     )
+
+
+# ---------------------------------------------------------------------------
+# DELETE /api/sessions/{name} — custom template (task: customizable delete command)
+# ---------------------------------------------------------------------------
+
+
+def test_delete_session_uses_template_command(client, monkeypatch, tmp_path):
+    """DELETE /api/sessions/{name} must execute the delete_session_template from settings.
+
+    The template {name} placeholder must be substituted with the session name.
+    The command must be run synchronously via subprocess.run (not run_tmux).
+    """
+    from unittest.mock import MagicMock, patch
+
+    # Make the session appear to exist so the 404 guard passes
+    monkeypatch.setattr("muxplex.main.get_session_list", lambda: ["myworkspace"])
+
+    # Redirect settings to a temp path so we can write a custom template
+    import muxplex.settings as settings_mod
+
+    fake_settings_path = tmp_path / "settings.json"
+    monkeypatch.setattr(settings_mod, "SETTINGS_PATH", fake_settings_path)
+
+    # Write a custom template
+    import json
+
+    fake_settings_path.write_text(
+        json.dumps(
+            {
+                "delete_session_template": "echo destroy {name}",
+            }
+        )
+    )
+
+    # Capture subprocess.run calls
+    captured_commands = []
+
+    def mock_run(cmd, **kwargs):
+        captured_commands.append(cmd)
+        result = MagicMock()
+        result.returncode = 0
+        result.stderr = ""
+        return result
+
+    with patch("muxplex.main.subprocess.run", side_effect=mock_run):
+        response = client.delete("/api/sessions/myworkspace")
+
+    assert response.status_code == 200, (
+        f"DELETE /api/sessions/myworkspace must return 200, got {response.status_code}"
+    )
+    data = response.json()
+    assert data.get("ok") is True, f"Response must have ok=True, got: {data}"
+    assert data.get("name") == "myworkspace", (
+        f"Response must have name='myworkspace', got: {data}"
+    )
+
+    # Verify template substitution happened
+    assert len(captured_commands) == 1, (
+        f"subprocess.run must be called exactly once, called {len(captured_commands)} times"
+    )
+    executed_cmd = captured_commands[0]
+    assert "myworkspace" in executed_cmd, (
+        f"Executed command must contain session name 'myworkspace', got: {executed_cmd!r}"
+    )
+    assert "echo destroy" in executed_cmd, (
+        f"Executed command must use the custom template, got: {executed_cmd!r}"
+    )
+
+
+def test_delete_session_default_template_is_tmux_kill(client, monkeypatch, tmp_path):
+    """DELETE /api/sessions/{name} uses 'tmux kill-session -t {name}' when no custom template is set."""
+    from unittest.mock import MagicMock, patch
+
+    monkeypatch.setattr("muxplex.main.get_session_list", lambda: ["mysession"])
+
+    # Redirect settings to empty temp file (no settings file = use defaults)
+    import muxplex.settings as settings_mod
+
+    fake_settings_path = tmp_path / "settings.json"
+    monkeypatch.setattr(settings_mod, "SETTINGS_PATH", fake_settings_path)
+    # Don't write any settings — defaults should be used
+
+    captured_commands = []
+
+    def mock_run(cmd, **kwargs):
+        captured_commands.append(cmd)
+        result = MagicMock()
+        result.returncode = 0
+        result.stderr = ""
+        return result
+
+    with patch("muxplex.main.subprocess.run", side_effect=mock_run):
+        response = client.delete("/api/sessions/mysession")
+
+    assert response.status_code == 200
+    assert len(captured_commands) == 1
+    executed_cmd = captured_commands[0]
+    # Default template substituted
+    assert "mysession" in executed_cmd, (
+        f"Default template must substitute session name, got: {executed_cmd!r}"
+    )
+    assert "kill-session" in executed_cmd, (
+        f"Default template must contain 'kill-session', got: {executed_cmd!r}"
+    )
diff --git a/muxplex/tests/test_frontend_html.py b/muxplex/tests/test_frontend_html.py
index 007b045..ef0320a 100644
--- a/muxplex/tests/test_frontend_html.py
+++ b/muxplex/tests/test_frontend_html.py
@@ -1062,3 +1062,94 @@ def test_html_settings_close_btn_exists() -> None:
     assert dialog.find(id="settings-close-btn") is not None, (
         "#settings-close-btn must be a descendant of #settings-dialog"
     )
+
+
+# ============================================================
+# Delete session template (task: customizable delete command)
+# ============================================================
+
+
+def test_html_delete_template_textarea_exists() -> None:
+    """New Session (Commands) panel must contain #setting-delete-template textarea."""
+    soup = _SOUP
+    dialog = soup.find(id="settings-dialog")
+    assert dialog is not None, "Missing #settings-dialog"
+    new_session_panel = dialog.find(
+        class_="settings-panel", attrs={"data-tab": "new-session"}
+    )
+    assert new_session_panel is not None, "Missing new-session settings-panel"
+    textarea = new_session_panel.find("textarea", id="setting-delete-template")
+    assert textarea is not None, (
+        "Missing