A planned halt is not an incident. It is a checkpoint you scheduled on purpose, and the whole art is arriving at it with every node holding the same binary.
A sovereign chain upgrades itself by stopping. This sounds like a contradiction until you see the mechanism. When the validator set passes a software-upgrade proposal, it does not agree to install new software. It agrees to halt at a named block height and refuse to produce block N+1 under the old binary. The upgrade is a coordinated pause, and the new software is what every node must be running before the chain will move again.
That reframing is the entire lesson. The 2026-07-04 genesis-restart lesson taught the unplanned halt: the chain stops because consensus broke, and the operators export state and rehearse a relaunch under pressure. Today is the mirror image. The 2026-06-27 governance lesson taught how a proposal passes. The upgrade-height halt is what that passed proposal does to the running chain. Between the two sits the operational discipline that keeps a hundred independent validators from fragmenting into two chains at the upgrade boundary.
The name for the automation is Cosmovisor. It is a small process supervisor that wraps the chain daemon, watches for the halt, swaps the binary, and relaunches. Done well, the operator sleeps through a mainnet upgrade. Done badly, half the validators come back on the wrong binary and the network splits. This lesson covers the mechanism, the failure surface, and the operational gates that make the swap boring, which is the only acceptable outcome for a scheduled event.
Three facts about Cosmos-SDK chains make automated upgrades both possible and dangerous.
First, consensus is deterministic and binary-sensitive. Every validator replays every transaction and must arrive at a byte-identical application state. Two binaries with different state-transition logic will compute different app-hashes for the same block, and the chain will refuse to finalize because the votes disagree on what the block means. This is why you cannot roll an upgrade one validator at a time the way you roll a stateless web fleet. The upgrade must be atomic across the set.
Second, the chain can name a future halt. The x/upgrade module stores an upgrade plan: a name and a height. When the chain reaches that height, every node running the module panics deliberately with a message that says, in effect, "UPGRADE REQUIRED: name at height H." The chain does not corrupt. It stops cleanly, one block short, with the state fully committed at H-1.
Third, the upgrade name maps to a directory. Cosmovisor's contract is filesystem-based. It expects binaries laid out under a cosmovisor/ root: a genesis/bin/ for the launch binary and an upgrades/<name>/bin/ for each named upgrade. When the daemon halts with UPGRADE REQUIRED: <name>, Cosmovisor reads the name, looks for upgrades/<name>/bin/, and if the binary is there, swaps the current symlink and relaunches. If the binary is not there, Cosmovisor either waits or exits, and the validator is now down until a human intervenes.
The SRE canon frames release engineering around exactly this property: releases should be hermetic and repeatable, so that the same inputs always produce the same artifact (Site Reliability Engineering, Part III, Release Engineering, p. 215). A chain upgrade is release engineering with the additional constraint that the release must land on every machine simultaneously or not at all.
Cosmovisor runs as the top-level process. Systemd starts Cosmovisor, and Cosmovisor starts the chain daemon as a child. Everything the daemon would normally receive is passed through untouched. The supervisor adds exactly one behavior: it interprets the daemon's exit. The lifecycle at the upgrade boundary runs in five moves.
The x/upgrade BeginBlocker matches the stored plan at height H and panics with UPGRADE REQUIRED. State is committed at H-1; nothing is half-written.
The daemon wrote upgrade-info.json before panicking. Cosmovisor reads the plan name from that file. The handoff signal is a file, not a network call.
Cosmovisor looks for upgrades/<name>/bin/. The pre-swap staging gate is that this binary is already present and verified before the halt arrives.
Cosmovisor repoints the current symlink and restarts the daemon. The upgrade handler runs its store migrations and resumes at H.
As >2/3 of bonded stake returns on the new binary and agrees on the app-hash at H, the chain finalizes H. Unstaged validators stay halted, not forked.
The property that makes this safe is that the halt is symmetric. Every honest node stops at the same height for the same reason. I call the swap itself the zero-touch binary swap: zero-touch because when the staging gate held, no human acts during the window. The operator's work happened days earlier, in staging, not at 3 a.m. during the halt.
Consider a validator on a Cosmos chain that has just passed proposal 42: upgrade v2.1.0 at height 18,500,000. The chain produces roughly one block every six seconds, so the operator can compute the wall-clock estimate of the halt and knows it lands in about four days.
The operator builds or downloads v2.1.0, verifies its checksum against the release's published hash, and places it at cosmovisor/upgrades/v2.1.0/bin/gaiad. This is the single most important step, and it is entirely front-loaded. The staging gate is closed by a human decision days ahead of the deadline, not by automation at the boundary. Today's Bash lesson builds exactly this staging pipeline.
Cosmovisor exposes its view of the world through the filesystem and through a dry-run. The operator confirms the upgrade directory exists, the binary is executable, and the expected upgrade is stageable. The telemetry discipline from the 2026-07-09 baselining lesson applies directly: the operator watches block height approach 18,500,000 and watches the per-validator performance panel for anyone drifting, because a validator already degraded going into an upgrade is the one most likely to miss the swap.
The daemon panics with UPGRADE REQUIRED: v2.1.0. On the well-staged validator, Cosmovisor reads the name, finds the staged binary, moves the symlink, and relaunches. The upgrade handler runs its store migrations. Blocks resume in seconds. On monitoring this shows as a brief gap in block production across the whole network, then a resumption. The gap is the network waiting for two-thirds of stake to come back on the new binary.
The operator confirms the node is signing under the new version, confirms the app-hash matches the rest of the network (not a private fork), and confirms no consensus-failure logs. The 2026-07-04 genesis-restart lesson is the fallback: if the migration corrupted state, the recovery path is the same coordinated-relaunch discipline, now executed against a known-bad upgrade.
This lesson closes a triangle the Chain arc has been drawing for three weeks. The 2026-06-27 governance lesson taught how a proposal passes and ended at ratification. Today shows what a ratified software-upgrade proposal does to the running chain: it arms the upgrade-height halt.
The 2026-07-04 genesis-restart lesson taught the unplanned halt and the export-edit-verify recovery. Today is the planned twin: the same clean-stop reflex triggered on purpose rather than by failure, automated by Cosmovisor rather than hand-rehearsed. The 2026-07-09 telemetry-baselining lesson supplies the instrument. You do not fly an upgrade blind: the block-interval baseline and the per-validator performance panel tell you the network is healthy going into the halt and reconverging cleanly coming out.
Today's Bash lesson builds the staging pipeline that closes the pre-swap staging gate: the fetch-checksum-place sequence, the upgrade-info watcher that tails upgrade-info.json and confirms the daemon saw the plan, and the idempotent pre-swap guard that re-runs safely without corrupting an already-staged binary. Where this Ops lesson names what Cosmovisor does at the boundary, the Dev lesson writes the shell that guarantees the boundary is boring. Cosmovisor is only zero-touch because the Bash staging ran correctly days earlier.
A chain upgrade is a scheduled halt that the whole validator set walks into together. Cosmovisor makes the swap automatic, but the automation only pays off when the binary was staged, checksummed, and verified before the halt arrived. The discipline is entirely front-loaded: the operator's real work is the staging gate, and the reward for closing it is a two-second swap that reads on the dashboard as a brief pause and a clean resume. Treat the upgrade like a release, arrive at the checkpoint with the artifact already in place, and the planned halt stays a checkpoint instead of becoming an incident.