Hydra Server operations
=======================

Setup
-----

Run this as the non-root Unix account that will own the terminal sessions:

    hydraterms remote

The enrollment code is requested by a hidden prompt. Never place it in the command line,
an environment variable, a service file, or shell history.

Upgrade without ending sessions
-------------------------------

Install the newer hydraterms-server package, then run:

    hydraterms remote

That rerun converges and restarts only the connectivity agent. It does not restart the retained
PTY daemon, so existing shells keep running. If the package contains a newer daemon binary, the
already-running daemon intentionally keeps its old executable until the next reboot or the
explicit destructive procedure below. A reboot ends live sessions and starts the new binary.

Remove connectivity but keep local sessions
--------------------------------------------

    hydraterms remove-remote --apply

This removes enrollment and the connectivity service. The independent PTY daemon and its local
sessions remain. Run `hydraterms remote` later with a fresh code to reconnect this Unix profile.

Switch this Unix profile to another Hydra cloud environment or account
-----------------------------------------------------------------------

First remove connectivity as above, then run `hydraterms remote` and enter a fresh code from the
destination account at the hidden prompt. The enrollment transaction releases the retired owner
marker only after proving active enrollment absent. It keeps the stable device key, independent PTY
daemon, retained sessions, and local projects; the passkey-authorized code's account becomes the new
remote owner.

Fully erase the retained daemon and local remote identity
---------------------------------------------------------

The following optional destructive transaction is not required to switch accounts. Use it only when
you also intend to end every retained Hydra session and replace the stable device key:

    hydraterms headless transfer-owner --apply --confirm-session-loss --confirm-cloud-ownership-transfer

This stops and removes the retained PTY daemon, proves its process, socket, unit, and every prior
session are absent, and only then retires the stable device key and durable owner marker. All
retained Hydra sessions end. After it reports success, run `hydraterms remote` and enter a fresh
code if remote access should be restored.

Account HOME and login-shell changes
------------------------------------

Changing the account's login shell is non-disruptive: new sessions use the current validated passwd
shell while existing sessions continue. Relocating the passwd HOME while Hydra is enrolled is not
supported. The agent retires remote access rather than mixing old provider history with a new HOME.
Restore the setup-time passwd HOME, run `hydraterms remove-remote --apply` and the confirmed daemon
removal command below, then relocate HOME and run setup again. Do not move or delete the unit files
or socket by hand.

Destroy the retained daemon and remove the package
--------------------------------------------------

These commands end every retained Hydra session. Run them as the session-owning account before
removing the package:

    hydraterms remove-remote --apply
    hydraterms headless remove-daemon --apply --confirm-session-loss
    sudo apt remove hydraterms-server

The daemon-removal command validates and stops only the reviewed hydra-pty-daemon user unit, then
proves its unit, process, and socket are absent. Package removal by itself cannot safely enter an
arbitrary user's systemd manager; running `apt remove` first can therefore leave an enabled user
unit or an old executable process alive. If the command refuses ambiguous state, do not delete the
unit or socket manually—repair or inspect the user service before retrying.
