A terminal panel beside an agent chat

A real shell on the chat's own connection, opened and closed like the
inspector and never beside it. The modes govern the model; what a person
types is theirs, since they hold the credential and could open the same
shell with an ssh client. The model cannot see the panel -- a button
copies the output you choose into the composer.

The session outlives the socket: closing the panel leaves a build
running, and coming back reattaches with the scrollback. Two tabs share
one shell and the smaller window decides the size. It ends on an idle
timeout, on deleting the chat, on disabling, moving or deleting the
connection, and on a restart -- which says why rather than quietly
opening a fresh shell that has lost the working directory.

The nginx template's `Connection ""` is right for SSE and fails every
WebSocket handshake, so `location /` now uses a `map $http_upgrade`;
update.sh grows a drift check for it, because the only symptom on a
stale vhost is a panel that cannot connect.

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

deploy/README.md

@@ -81,6 +81,29 @@ delivers it in one lump at the end, which is indistinguishable from streaming
 being broken. `proxy_read_timeout` is raised to an hour because a model can
 think for minutes before the first token.
 
+**The vhost passes WebSocket upgrades through, and must.** The terminal panel
+is the one WebSocket in LLeMbas. A `location` that sets `Connection ""` — which
+is what SSE alone needs, and what this template used to say — fails every
+handshake, and a failed handshake tells the browser nothing: no status, no
+reason. The `map $http_upgrade` at the top of the vhost yields the empty string
+when the client did not ask to upgrade, so streaming is unaffected. `update.sh`
+warns when the installed vhost has drifted from the template, because this is
+the failure most likely to be diagnosed as a bug in the application.
+
+**Every restart kills every open shell.** A reply being written is persisted
+with whatever it has; a terminal has nothing to persist, so a command still
+running on the far side is cut off. `update.sh` restarts unconditionally, so a
+deploy in the middle of somebody's `apt-get dist-upgrade` ends it. The panel is
+told why rather than silently reconnecting to a new shell, which would have
+lost the working directory and the half-typed command.
+
+**A terminal is not in the transcript, and is not logged.** The open and the
+close are logged with the user, the chat and the connection; what was typed is
+not recorded anywhere. That follows from the design — the chat's mode governs
+the model, not the person at the keyboard — but everything else an agent chat
+does *is* in the transcript, so it is a difference in kind and worth knowing
+before somebody goes looking for the history.
+
 **Nothing an agent does runs on this machine.** Agent chats execute their
 commands over SSH, on a host somebody added and prepared — a container, a VM,
 another machine. That is the whole isolation story, and it is why the unit can
@@ -97,3 +120,14 @@ key to a production server, and LLeMbas cannot tell them apart.
 **Use a real certificate if this is exposed beyond a trusted LAN.** The
 self-signed cert exists so the install works with no external dependencies;
 point `ssl_certificate` at a real one and nothing else needs to change.
+
+The session cookie is deliberately not marked `secure`, so that a LAN install
+over plain http can sign anybody in at all. That has always meant a network
+attacker on http could steal a session; with the terminal it also means they
+could open an interactive shell on the machine behind that chat. If the
+terminal is switched on, run this over TLS.
+
+**One worker only.** True of generations already — the registry is in-process —
+and sharper here: with two workers a browser reconnecting to its terminal could
+land in the process that has no shell for it, and silently open a second one on
+the same machine.

deploy/install.sh

@@ -136,6 +136,14 @@ sed -e "s|__SITE_HOST__|$SITE_HOST|g" -e "s|__APP_PORT__|$APP_PORT|g" \
 sudo nginx -t
 sudo systemctl reload nginx
 
+# What this host was installed with, so update.sh can name the vhost it should
+# be comparing against and print a command that actually runs. Without it the
+# drift check below could only say "something changed somewhere".
+printf 'SITE_HOST=%s\nAPP_PORT=%s\n' "$SITE_HOST" "$APP_PORT" \
+  | sudo tee "$PREFIX/.deploy-env" >/dev/null
+sha256sum "$HERE/nginx-vhost.conf" | cut -d' ' -f1 \
+  | sudo tee "$PREFIX/.vhost-applied" >/dev/null
+
 echo "== local name resolution =="
 # Only useful when the LAN's DNS does not already answer for this name.
 if ! getent hosts "$SITE_HOST" >/dev/null; then

deploy/nginx-vhost.conf

@@ -7,6 +7,19 @@
 # install.sh generates. To use a real certificate, point ssl_certificate at it;
 # nothing else here needs to change.
 
+# The terminal panel is a WebSocket, and a proxy that does not pass an upgrade
+# through breaks it with no error either side can report -- the browser sees a
+# failed handshake, which carries no status and no reason. This map yields
+# "upgrade" only when the client asked for one and the empty string otherwise,
+# which is exactly what the streamed-reply case below needs, so one `location`
+# serves both. `conf.d/*.conf` is included inside `http {}`, where `map` is
+# legal; the name is prefixed because two vhosts from this template would
+# otherwise collide.
+map $http_upgrade $lembas_connection_upgrade {
+    default upgrade;
+    ''      '';
+}
+
 server {
     listen 80;
     listen [::]:80;
@@ -42,9 +55,13 @@ server {
         proxy_buffering         off;
         proxy_request_buffering off;
         proxy_cache             off;
-        # SSE is plain HTTP/1.1 chunked, not a websocket upgrade, so the
-        # connection header must simply be left to keep-alive.
-        proxy_set_header Connection "";
+        # SSE is plain HTTP/1.1 chunked and needs Connection left empty; the
+        # terminal is a real upgrade and needs it set. The map at the top of
+        # this file is what lets one location do both -- a hard-coded
+        # `Connection ""` here, which is what was here before, works for every
+        # streamed reply and silently breaks every terminal.
+        proxy_set_header Upgrade    $http_upgrade;
+        proxy_set_header Connection $lembas_connection_upgrade;
 
         # A model can think for minutes before the first token. The default
         # 60s read timeout would cut long generations off mid-sentence.

deploy/update.sh

@@ -56,9 +56,8 @@ sudo -u "$SERVICE_USER" "$VENV/bin/pip" install --quiet -e "$APP[$LEMBAS_EXTRAS]
 # about the local lines, and a warning that always fires is one nobody reads.
 #
 # The drift is worth catching: a change in the unit can be what makes a release
-# work at all. Dropping ProtectKernelTunables is why an agent chat can start a
-# sandbox, and a host that pulled the code without it would run the new version
-# under the old confinement and fail confusingly.
+# work at all, and a host that pulled the code without it would run the new
+# version under the old settings and fail confusingly.
 STAMP="$PREFIX/.unit-applied"
 current=$(sha256sum "$APP/deploy/lembas.service" | cut -d' ' -f1)
 if [[ -f "$STAMP" && "$(cat "$STAMP")" != "$current" ]]; then
@@ -77,6 +76,48 @@ elif [[ ! -f "$STAMP" ]]; then
   echo "$current" | sudo tee "$STAMP" >/dev/null
 fi
 
+# The same argument for the vhost, and the failure is worse. A stale unit at
+# least says something in the journal; a stale vhost breaks a feature two layers
+# away, and the only symptom is a panel that says it could not connect. The
+# terminal is a WebSocket, and a `location` that does not pass an upgrade
+# through fails every handshake while every test in the suite still passes.
+VHOST_STAMP="$PREFIX/.vhost-applied"
+vhost_now=$(sha256sum "$APP/deploy/nginx-vhost.conf" | cut -d' ' -f1)
+
+site_host=""; app_port="8080"
+# Written by install.sh. Absent on a deployment that predates it, in which case
+# the commands below are a template rather than a copy-paste.
+if [[ -f "$PREFIX/.deploy-env" ]]; then
+  . "$PREFIX/.deploy-env"
+  site_host="$SITE_HOST"; app_port="$APP_PORT"
+fi
+installed_vhost="/etc/nginx/conf.d/${site_host:-your-host}.conf"
+
+vhost_stale=""
+if [[ -f "$VHOST_STAMP" ]]; then
+  [[ "$(cat "$VHOST_STAMP")" != "$vhost_now" ]] && vhost_stale="the template has changed"
+elif [[ -n "$site_host" && -f "$installed_vhost" ]]; then
+  # First run with this check, so there is no stamp to compare against. Rather
+  # than assume what is installed is current -- which is what the unit check
+  # does, and would hide exactly the change this was added for -- look for the
+  # one thing that must be there. Everything else is left to the stamp.
+  grep -q 'lembas_connection_upgrade' "$installed_vhost" \
+    || vhost_stale="the installed vhost does not pass WebSocket upgrades through, so the terminal cannot connect"
+fi
+
+if [[ -n "$vhost_stale" ]]; then
+  echo "== nginx vhost ==" >&2
+  echo "   $vhost_stale." >&2
+  echo "   Review and reinstall it:" >&2
+  echo "     diff $installed_vhost <(sed \\" >&2
+  echo "       -e 's|__SITE_HOST__|${site_host:-your-host}|g' -e 's|__APP_PORT__|$app_port|g' \\" >&2
+  echo "       $APP/deploy/nginx-vhost.conf)" >&2
+  echo "   Then: sudo nginx -t && sudo systemctl reload nginx" >&2
+  echo "   And record it as applied: echo $vhost_now | sudo tee $VHOST_STAMP" >&2
+elif [[ ! -f "$VHOST_STAMP" ]]; then
+  echo "$vhost_now" | sudo tee "$VHOST_STAMP" >/dev/null
+fi
+
 echo "== restart =="
 sudo systemctl restart lembas
 sleep 2