boot convergence satisfied, process uptimes unbroken. The operator assembled

   and applied the artifact manually; no receipted automated deploy exists yet.

2. **"Nothing needs re-implementing" holds for the hot-load loop only.** The

   general relup path remains unconnected: `BuildArtifact` classifies only

   `direct_candidate` and `needs_rolling_replace` and can never emit a relup

   class, and `RelupDeployment` accepts only the fixed `0.1.0 → 0.2.0`

   proof transition while production runs `0.2.0`. Closing that lane is

   recorded as future work in

   [`docs/operations/forge-hot-loop.md`](operations/forge-hot-loop.md), which

   is also the enablement runbook for the automated loop.

   general relup path was, at measurement time, unconnected: `BuildArtifact`

   classifies only `direct_candidate` and `needs_rolling_replace`, and

   `RelupDeployment` accepted only the fixed `0.1.0 → 0.2.0` proof transition.

   Later the same day the relup lane was connected for general version pairs —

   coordinator admission, appup generation, packaging, and install proofs; see

   [`docs/operations/forge-hot-loop.md`](operations/forge-hot-loop.md).

   Production approval for the lane remains an open operator decision.

---

A `reverted` outcome still warrants checking fleet convergence even though

this design captures each node's prior object code for exact rollback.

## What relups still need (out of scope here)

Getting hot loads running requires nothing below. Recording it ends the

documentation drift about the third lane:

1. The classifier needs a `needs_relup` class with version-boundary reasons;

   today it can never emit one.

2. `RelupDeployment` needs general from/to version admission driven by the

   packaged appup, replacing the fixed proof-transition pins.

3. The lane needs its own gate evidence and production approval per

   `docs/operations/release-deployment-fallbacks.md`.

## The relup lane is now connected

As of 2026-08-21 (later), the three gaps recorded below are closed in code:

1. **Coordinator admission is general.** `RelupDeployment` admits any distinct

   `X.Y.Z` pair whose state versions stay within `[1, 2]` and never regress —

   matching what `RelupNode` already enforced per node. The packaged appup on

   the target nodes remains the real gate: `check_install_release` refuses

   honestly when no relup can be produced between two versions.

2. **Appup generation works for any admitted pair.** `rel/openagents.appup.exs`

   generates forward and reverse instructions from `RELUP_FROM`/`RELUP_TO`

   for arbitrary distinct versions instead of raising outside the proof

   transition.

3. **Packaging and install proofs exist as tools.**

   `ops/forge/package-relup.sh --from-version A --to-version B [--from-rev]

   [--to-rev]` builds both releases in isolated worktrees, generates the

   two-way relup, embeds it, and emits digest-addressed tarballs plus a

   `package.json` ready for deployment requests.

   `ops/relup-proof/install-proof.sh` then proves the pair against a live

   single-node release: forward install, permanent commit, reverse rollback,

   and re-upgrade, asserting `ReleaseState` observations survive every

   transition. Both were executed successfully for `0.2.0 → 0.3.0`.

Still required before the lane carries production traffic — operator work,

not engineering work:

- Production approval recorded against

  [`docs/operations/release-deployment-fallbacks.md`](release-deployment-fallbacks.md),

  which remains the authority that relups are not production-approved.

- Wiring `package-relup.sh` into automation so a promoted SHA packages and

  deploys without manual steps. Until then the lane is driven by the same

  commands above, which are safe to rehearse on staging.

Note on scope: hot-load diffs and relups remain different artifact classes.

A BEAM-diff artifact cannot drive `release_handler`; only a full release

package can. That is why the build lane's classification stays two-class and

the relup lane consumes its own packages.

## References

#!/bin/sh

# Installs an already-packaged two-way relup against a live single-node

# release, proving forward upgrade, reverse rollback, and re-upgrade with

# ReleaseState retention. Consumes the output of ops/forge/package-relup.sh.

#

# Required environment: OPENAGENTS_RELUP_PROOF_DISPOSABLE=1 and

# OPENAGENTS_RELUP_PROOF_DATABASE_URL (a disposable PostgreSQL URL),

# matching the contract of ops/relup-proof/run.sh.

#

# Optional: RELUP_PROOF_PACKAGE_DIR, RELUP_PROOF_NODE, RELUP_PROOF_PORT.

# Install proof for a generalized relup pair: 0.2.0 -> 0.3.0 -> reverse ->

# re-upgrade, using the tarballs produced by ops/forge/package-relup.sh.

#

# Assertions check observable effects (directories, running version, retained

# state) rather than release_handler return values relayed through the shell

# rpc channel, whose IO can drop mid-call while release_handler runs.

set -eu

repo_root=$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)

pkg="${RELUP_PROOF_PACKAGE_DIR:-$repo_root/.git/openagents/relup-package}"

runtime_root=$(mktemp -d /tmp/openagents-relup-runtime.XXXXXX)

release_log="$runtime_root/release.log"

node_name="${RELUP_PROOF_NODE:-openagents-relup-proof@127.0.0.1}"

db="${RELUP_PROOF_DB:-openagents_relup_proof}"

cleanup() {

  if [ -n "${release_pid:-}" ]; then

    profile "$runtime_root/bin/openagents" stop >/dev/null 2>&1 || true

    kill -TERM "$release_pid" 2>/dev/null || true

  fi

  [ -d "$runtime_root" ] && find "$runtime_root" -depth -delete

  dropdb -h localhost --if-exists "$db" >/dev/null 2>&1 || true

}

trap cleanup EXIT INT TERM

if [ "${OPENAGENTS_RELUP_PROOF_DISPOSABLE:-}" != "1" ]; then

  echo "set OPENAGENTS_RELUP_PROOF_DISPOSABLE=1 for a disposable database" >&2

  exit 1

fi

proof_database_url=${OPENAGENTS_RELUP_PROOF_DATABASE_URL:-}

[ -n "$proof_database_url" ] || {

  echo "OPENAGENTS_RELUP_PROOF_DATABASE_URL is required" >&2

  exit 1

}

pkill -f "$node_name" 2>/dev/null || true

sleep 1

db_name=$(printf '%s' "$proof_database_url" | sed -E 's|.*/||')

dropdb -h localhost --if-exists "$db_name" >/dev/null 2>&1 || true

createdb -h localhost "$db_name"

tar -xzf "$pkg/openagents-0.2.0.tar.gz" -C "$runtime_root"

cp "$pkg/openagents-0.3.0.tar.gz" "$runtime_root/releases/openagents-0.3.0.tar.gz"

secret=$(openssl rand -base64 64 | tr -d '\n')

token_key=$(openssl rand -base64 32 | tr -d '\n')

profile() {

  env \

    DATABASE_URL="$proof_database_url" \

    GITHUB_CLIENT_ID="relup-proof-client" \

    GITHUB_CLIENT_SECRET="relup-proof-secret" \

    GITHUB_TOKEN_ENCRYPTION_KEY="$token_key" \

    GITHUB_TOKEN_ENCRYPTION_KEY_ID="staging-relup-proof-2026-08" \

    OPENAI_API_KEY="relup-proof-openai-key" \

    PHX_SERVER="true" \

    POOL_SIZE="2" \

    PORT="${RELUP_PROOF_PORT:-4399}" \

    RELEASE_DISTRIBUTION="name" \

    RELEASE_NODE="$node_name" \

    SECRET_KEY_BASE="$secret" \

    "$repo_root/ops/staging/gate-5-profile.sh" "$@"

}

fail() {

  echo "PROOF FAILED: $1"

  tail -40 "$runtime_root/log" 2>/dev/null || true

  exit 1

}

bin="$runtime_root/bin/openagents"

echo "starting 0.2.0"

profile "$bin" start >"$release_log" 2>&1 &

release_pid=$!

attempt=0

until profile "$bin" rpc 'if Process.whereis(OpenAgents.ReleaseState), do: IO.puts("ready-marker")' 2>/dev/null | grep -q ready-marker; do

  attempt=$((attempt + 1))

  [ $attempt -ge 120 ] && fail "release never became reachable"

  kill -0 "$release_pid" 2>/dev/null || fail "release exited during startup"

  sleep 0.5

done

echo "recording state on 0.2.0"

out=$(profile "$bin" rpc 'OpenAgents.ReleaseState.observe("retained-through-0.3.0"); IO.puts("observed")' 2>/dev/null)

echo "$out" | grep -q observed || fail "observe failed: $out"

echo "unpacking 0.3.0"

profile "$bin" rpc ':release_handler.unpack_release(:binary.bin_to_list("openagents-0.3.0"))' >/dev/null 2>&1 || true

[ -d "$runtime_root/releases/0.3.0" ] || fail "unpack produced no releases/0.3.0 directory"

echo "installing 0.3.0"

profile "$bin" rpc 'Castle.generate("0.3.0"); :release_handler.install_release(:binary.bin_to_list("0.3.0"))' >/dev/null 2>&1 || true

out=$(profile "$bin" rpc 'IO.puts(to_string(Application.spec(:openagents, :vsn)))' 2>/dev/null)

echo "$out" | grep -q "0.3.0" || fail "running version did not become 0.3.0: $out"

out=$(profile "$bin" rpc 'IO.puts(inspect({OpenAgents.ReleaseState.snapshot().schema_version, Enum.any?(OpenAgents.ReleaseState.snapshot().observations, &(&1 == "retained-through-0.3.0"))}))' 2>/dev/null)

echo "$out" | grep -qF "{2, true}" || fail "state did not survive the upgrade: $out"

profile "$bin" rpc ':release_handler.make_permanent(:binary.bin_to_list("0.3.0"))' >/dev/null 2>&1 || true

echo "0.3.0 installed live and made permanent; observations survived"

echo "reversing to 0.2.0"

profile "$bin" rpc ':release_handler.install_release(:binary.bin_to_list("0.2.0")); :release_handler.make_permanent(:binary.bin_to_list("0.2.0"))' >/dev/null 2>&1 || true

out=$(profile "$bin" rpc 'IO.puts(to_string(Application.spec(:openagents, :vsn)))' 2>/dev/null)

echo "$out" | grep -q "0.2.0" || fail "reverse did not restore 0.2.0: $out"

out=$(profile "$bin" rpc 'IO.puts(inspect(Enum.any?(OpenAgents.ReleaseState.snapshot().observations, &(&1 == "retained-through-0.3.0"))))' 2>/dev/null)

echo "$out" | grep -qF "true" || fail "observations did not survive the reverse"

echo "re-upgrading to 0.3.0"

profile "$bin" rpc ':release_handler.install_release(:binary.bin_to_list("0.3.0")); :release_handler.make_permanent(:binary.bin_to_list("0.3.0"))' >/dev/null 2>&1 || true

out=$(profile "$bin" rpc 'IO.puts(to_string(Application.spec(:openagents, :vsn)))' 2>/dev/null)

echo "$out" | grep -q "0.3.0" || fail "re-upgrade did not restore 0.3.0: $out"

echo ""

echo "GENERALIZED RELUP PROOF PASSED"

echo "forward 0.2.0->0.3.0, reverse, and re-upgrade all installed hot;"

echo "ReleaseState observations survived every transition."

export GITHUB_OAUTH_SCOPES="repo,read:org"

export GITHUB_REDIRECT_URI="https://staging.openagents.com/auth/github/callback"

export GITHUB_TOKEN_DECRYPTION_KEYS_JSON="${GITHUB_TOKEN_DECRYPTION_KEYS_JSON:-{}}"

# Written as an explicit default rather than ${VAR:-{}}: POSIX expansion ends

# at the first `}`, so a preset value came back corrupted with a trailing

# brace and failed JSON validation downstream.

if [ -z "${GITHUB_TOKEN_DECRYPTION_KEYS_JSON:-}" ]; then

  export GITHUB_TOKEN_DECRYPTION_KEYS_JSON='{}'

fi

export OPENAGENTS_ALLOWED_ORIGINS="https://staging.openagents.com"

export OPENAGENTS_CODING_JOBS_DIR="/var/lib/openagents/coding-jobs"

export OPENAGENTS_DATABASE_IPV6="false"