Update & rollback

The release layout is what makes both cheap

~/.local/share/agent-sessions/
├── releases/<ts>-<sha>/{src,venv}   one self-contained release per build
├── current → releases/<ts>-<sha>     atomic symlink; flipping it IS the upgrade
└── env                               0600; secret + admin hash + host/port/origin

Each release is an immutable directory with its own virtualenv. current is a symlink, so an upgrade and a rollback are the same operation in opposite directions — a re-point, not a rebuild. Re-running the installer is idempotent: it builds a new release, flips current, keeps the previous releases (3 by default), and leaves your credentials untouched.

Updating

Self-update never runs arbitrary input. It moves to the channel's latest release, flips current, restarts, health-checks /healthz, and rolls back automatically if the new release fails that check.

• In-app — Settings → System → Updates shows the running version with check/apply controls (/api/version, /api/update/check, /api/update/apply; authed, CSRF- and origin-gated).
• CLI — agent-sessions autoupdate checks the channel and applies only if newer.
• Automatic — the same guarded check/apply runs daily. On by default, for BattleLab and for the agents you installed from the catalog (Agent catalog). Pause under Settings → Updates stops both; Resume turns them back on.

The channel selector switches between stable (the highest v* tag) and main (bleeding edge). Both the channel and Pause persist server-side and apply live — no reinstall, no environment variable. Installs that used the old AGENT_SESSIONS_AUTOUPDATE=1 systemd timer migrate on upgrade and the legacy timer units are removed. An install whose agent catalog check was turned off is shown as Paused, so its earlier choice stays visible.

Rolling back by hand

P=~/.local/share/agent-sessions
ls -1dt $P/releases/*/                       # newest first; pick the known-good one
# atomic re-point — temp-link + rename(2), the same idiom the installer uses
ln -s $P/releases/<ts>-<sha> $P/.current.rb && mv -Tf $P/.current.rb $P/current
systemctl --user restart agent-sessions.service

Do not use ln -sfn

ln -sfn unlinks before it relinks, so a concurrent start or health-check can observe a moment with no current at all. The temp-link + mv -Tf above is a single rename(2): an observer sees either the old target or the new one, never nothing.

A failed self-update or auto-update has already rolled itself back; the above is the manual path for "the new release starts fine but behaves wrong".

Emergency disable

systemctl --user stop    agent-sessions.service   # take it down now
systemctl --user disable agent-sessions.service   # …and keep it down across logins
journalctl --user -u agent-sessions.service -f    # logs

To stop automatic updates only, press Pause under Settings → Updates, or set AGENT_SESSIONS_AUTOUPDATE=0 in ~/.local/share/agent-sessions/env.

Verified against

Commit 218cf3a — README.md § Updating / Rollback & emergency-disable; docs/reference.md § Install / update.