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 account.

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

An ordinary Remote removal deliberately preserves the durable cloud/account owner so a different
account cannot inherit detached terminal sessions. To transfer ownership, first remove connectivity
as above, then run the explicit destructive transaction:

    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 one fresh
code from the destination environment at the hidden prompt.

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.
