Upgrades

Hikyo migrations move forward only. A downgrade means restoring a pre-upgrade archive with a compatible binary, not running a down migration.

Release channels

stable follows signed production releases. nightly follows unsigned GitHub prereleases built from the newest green, changed main commit. A stable 1.0.0 makes the nightly line 1.1.0-nightly.<date>.<run>.g<sha>; after stable 1.1.0, it advances to 1.2.0-nightly.... Nightlies are evaluation artifacts, not production releases.

Before any stable release exists, the first line is 0.0.1-nightly.<date>.<run>.g<sha>. Release discovery is paginated; a long nightly history cannot hide the latest published stable release.

Server-side and remote workspace checks are notification-only. Remote apply is disabled for every release channel because the legacy helper cannot prove safe rollback once a migration has started. Signed release discovery and verified manual downloads remain available.

Release binaries also check their own CLI track before dispatching a command when stderr and a controlling terminal are available. Stable artifacts default to stable, nightly artifacts default to nightly, and binaries built directly from source default to off. A local hikyo update channel ... choice is persisted and overrides a published artifact’s default. Source builds remain off; install a published artifact to join a release channel.

At most once per 24 hours, Hikyo refreshes the selected track. When a newer release exists, the controlling terminal asks whether to install it. Accepting downloads the exact archive for the running OS and architecture. Nightlies require GitHub’s immutable asset digest plus GoReleaser’s checksums.txt. Stable updates additionally require an immutable release and use Hikyo’s in-process, recovery-root-pinned signature verifier over the current trust metadata, signed manifest, candidate, and selected archive. No external shell, jq, or cosign executable participates in the self-update trust boundary.

After verification Hikyo extracts only the expected executable, takes a cross-process replacement lock, and writes and syncs a unique same-directory file. Unix atomically renames it over the resolved binary. Windows recoverably moves the mapped old image aside before publishing the replacement at the original path, then removes the backup on a later start after its last process exits. The current command stops before dispatch. Repeat the command to run the new version. An already running hikyo server process keeps its old in-memory image until its service is restarted.

The updater never elevates privileges. If the current binary is managed by a system package or is not writable by the current user, the replacement fails without changing it; use that installation’s package or service procedure. hikyo update check bypasses the 24-hour refresh interval and performs the same confirmation flow immediately.

Remote apply is disabled

The legacy hikyo updater helper and its Compose, systemd, and Flux adapters are retired. They could automatically restore a database after schema writes had started; the Flux adapter also used ambient Git credentials. No replacement platform apply path or migration-generation gate is implemented by this change.

HIKYO_UPDATER_SOCKET now prevents server startup. Remove that setting to start the server with release notifications. hikyo updater refuses before reading configuration, touching its socket or journal, or starting commands. The shipped platform adapters refuse every phase, including rollback. The API reports apply_supported: false with a migration-safety reason; authenticated apply requests are refused and never submitted to a helper. The WebUI also refuses legacy apply advertised by an older remote instance.

Before installing this release, stop and disable every existing updater helper service and check for already running backend commands. Replacing a binary on disk cannot stop an old process or a previously spawned privileged child. Preserve jobs.json and deployment logs as historical evidence; do not replay queued jobs or infer a safe rollback from a legacy journal’s phase. If an earlier attempt reached apply, investigate the datastore and use the operator-led recovery procedure below. Retirement does not mark existing jobs successful or restored.

Every connected workspace still checks release metadata directly. Administrators retain update notifications and links to release notes. Upgrades use the manual signed-bundle and maintenance procedure below. The viewing instance holds no fleet deployment credentials.

For stable artifacts, use the installation and release-verification instructions to obtain and verify the signed bundle before the maintenance window.

Before the change

1. Read the release notes and support status.
2. Record the running binary version and datastore engine.
3. Confirm the root key and backup identity are available through separate paths.
4. Run hikyo backup export and copy the archive off-host.
5. Verify recent restore-drill evidence.

Do not begin when you can create an archive but cannot prove which root key will boot it.

Automatic migration

hikyo server applies pending migrations by default. When backup recipients and a destination are configured, it exports the old schema before changing it.

A configured export failure stops startup. An unconfigured policy records a loud skip and continues, leaving no rollback archive.

Controlled migration

For a maintenance window:

1. Stop the server.
2. Take and retain a manual export.
3. Install the new reviewed binary.
4. Run hikyo migrate with the production HIKYO_DB.
5. Start hikyo server --auto-migrate=false and check both probes.

With automatic migration disabled, the server refuses to serve when a migration is pending or the database schema is newer than the binary.

Verify the upgrade

curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/readyz
hikyo doctor --instance hikyo.example.com
hikyo whoami --instance hikyo.example.com

Also verify one authorized metadata read and one representative workload. A health response alone does not prove authentication, authorization, or delivery.

Roll back

Stop the failed instance. Restore the pre-upgrade archive into an empty target with a binary that supports its schema, then follow the full reconciliation procedure.

Restoring invalidates all old authenticators. Include human recovery and machine credential redistribution in the rollback time estimate.

See backup and restore for the complete flow.