Upgrading sysg

Run the normal installer again to upgrade to the latest release:

$ curl --proto '=https' --tlsv1.2 -fsSL https://sh.sysg.dev/ | sh

Live re-execution

Starting with 0.56.0, compatible releases use live re-execution: the running supervisor replaces its process image in the same PID while retaining its service processes, process groups, control socket, log pipes, project modes, and lifecycle state.

The installer performs the upgrade in this order:

1. Download the release into its versioned slot.
2. Verify its version, executable metadata, protocol, and handoff schema.
3. Ask the resident supervisor whether its runtime is safe to transfer.
4. Re-execute the supervisor and verify that the same PID reports the target version.
5. Update the sysg symlink and active-version file.

The PATH target is not changed if any step fails. A foreground log attachment may reconnect while the supervisor image changes, but its project and service processes continue running.

Compatibility

Live re-execution requires a strictly newer release with the same live-reexec protocol and handoff schema. Version boundaries do not determine compatibility: 0.57.1 can live-upgrade to 0.58.0 while both advertise the same contract. A downgrade or a protocol/schema change requires a stopped supervisor.

Contract-based compatibility begins with 0.57.1. Residents from 0.56.0 through 0.57.0 enforce the original same-major/minor rule, while earlier residents do not support live re-execution. Upgrading from 0.56.x to 0.57.x therefore requires one stopped-supervisor transition:

$ sysg stop --supervisor
$ curl --proto '=https' --tlsv1.2 -fsSL https://sh.sysg.dev/ | sh

The installer reports SG0502 and leaves the existing PATH target unchanged when the resident and target cannot hand off safely. The target remains installed, so stopping the supervisor and rerunning the same installer activates it.

Safe handoff requirements

The supervisor waits for a stable ownership boundary. It refuses the upgrade while a project is booting, a restart or deployment is active, a cron command is running, or dynamic child processes cannot be transferred. It also verifies that loaded manifests have not changed and that every managed output pipe can be inherited.

The refusal is non-destructive. Let the reported operation finish, then rerun the installer.

Failure and rollback

The previous versioned binary remains installed until the replacement has restored supervision. Failures before exec produce SG0504 and the resident supervisor resumes normally. If the replacement cannot restore the handoff, systemg attempts to re-execute the previous binary and reports SG0505.

Upgrade diagnostics are documented from SG0501 through SG0505.