Add passive agent lifecycle packaging

[BadgerOps]

Summary

This PR implements the next packaging/distribution slice for passive-agent issue #53.

It focuses on lifecycle management for already-versioned agent releases:

• versioned install directories on the host
• stable current symlink switching
• upgrade, rollback, and uninstall helper scripts
• checksum publication for the release tarball
• packaging tests for install and rollback behavior
• docs for verification, upgrade, rollback, and uninstall

Related: #53.

What Changed

Versioned host install layout

Changed the host install model from a single in-place runtime copy to a versioned release layout:

• /opt/grapheon/agent/releases/<version>/
• /opt/grapheon/agent/current

install-passive-agent.sh now installs the runtime into the versioned release directory and repoints current to the new version.

deploy/grapheon-agent.service now runs:

• /opt/grapheon/agent/current/grapheon_agent.py

This means upgrades and rollbacks can switch versions without rewriting the unit file.

Lifecycle helper scripts

Added:

• scripts/upgrade-passive-agent.sh
• scripts/rollback-passive-agent.sh
• scripts/uninstall-passive-agent.sh

Behavior:

• upgrade-passive-agent.sh installs the new versioned release and reports the previous/current version
• rollback-passive-agent.sh <version> repoints current to an already-installed prior release
• uninstall-passive-agent.sh removes agent files and units, with optional --purge-state

This makes lifecycle management reproducible instead of manual file copying.

Artifact and release metadata

Extended the release artifact contents to include the lifecycle scripts.

Extended the GitHub release workflow so the passive-agent release also uploads:

• grapheon-agent-vX.Y.Z.tar.gz.sha256

That gives operators a minimal verification path for downloaded release artifacts.

Tests

Added packaging-focused tests in:

• agent/tests/test_packaging_scripts.py

Coverage includes:

• versioned install layout creation
• current symlink targeting the installed release
• rollback repointing current to an older installed version
• fake systemctl integration so lifecycle behavior is tested without requiring systemd in CI

Version and changelog

Bumped the passive agent version:

• agent/VERSION -> 0.3.0

Updated:

• agent/CHANGELOG.md

The changelog entry covers:

• versioned install layout
• lifecycle scripts
• rollback test coverage
• checksum publication
• packaging doc updates

Files Of Interest

• deploy/grapheon-agent.service
• scripts/install-passive-agent.sh
• scripts/upgrade-passive-agent.sh
• scripts/rollback-passive-agent.sh
• scripts/uninstall-passive-agent.sh
• scripts/build-agent-artifact.sh
• .github/workflows/release.yml
• agent/tests/test_packaging_scripts.py
• agent/VERSION
• agent/CHANGELOG.md
• docs/agent_quickstart.md
• docs/release-process.md

Testing

Ran:

• python3 scripts/validate_versions.py
• bash -n scripts/build-agent-artifact.sh scripts/install-passive-agent.sh scripts/upgrade-passive-agent.sh scripts/rollback-passive-agent.sh scripts/uninstall-passive-agent.sh
• bash scripts/build-agent-artifact.sh 0.3.0 /tmp/grapheon-agent-v0.3.0.tar.gz
• tar -tzf /tmp/grapheon-agent-v0.3.0.tar.gz
• nix develop -c .venv/bin/python -m pytest agent/tests/test_packaging_scripts.py
• nix develop -c .venv/bin/python -m pytest

Result:

• full suite passes on this branch: 369 passed, 1 skipped

Scope Notes

This PR does not add distro-native packages (.deb / .rpm) or artifact signing yet.

What it does add is the first practical release-lifecycle layer on top of the existing agent artifact and image work:

• install without a repo checkout already existed on master via the tarball
• this PR makes upgrades and rollbacks operationally sane
• this PR adds verification metadata and test coverage for the lifecycle scripts