opschain admin agent rollover

packs:agentspacks:agent-governance

opschain admin agent rollover <agent> --to <name>@<version> [--lane <lane>] \
    [--strategy replace|canary=<n>|blue-green] [--green-lane <lane>] [--size <n>] \
    [--drain|--drain-only] [--approver <user>]... [--reason <text>] [--server <url>] [--auth-token <token>]
opschain admin agent rollover <continue|abort|rollback|finish> <agent> [--lane <lane>]
opschain admin agent rollover show <agent> [--lane <lane>] [--id <rollover>]

Moves one lane of an agent from the release its instances run to another release (v2 AgentService.RolloverAgent) — the platform verb behind "change the agent": no stop-and-hope, no second project. The rollover:

1. refuses unless the target release's stage satisfies every stage floor the agent's scopes require — the estate's agents.release_stage, the release_stage_floor of every environment the agent's trust grants reach, and those grants' release_stage conditions (a dev build is never rolled into a lane that serves production), and unless the release is still serving — a retired or revoked release refuses by name, as does a lane with no live instance, a lane already running the release on every instance, and a lane whose previous rollover is still open;
2. drains each targeted instance — in-flight work finishes, nothing new is dispatched to it (the routine lifecycle tier);
3. instructs the restart over the instance's own channel: the runtime keeps its state directory and keypair, fetches and verifies the release's artifact (or, where it cannot replace its own image — a container — exits with code 75 for the container platform's restart policy to bring it back on the image the release names), re-enrols from the new release and, verified at enrolment, resumes dispatch;
4. attests every step on the release (opschain admin agent-release show) and lands the info:agent:rollover_* events on the agent's path, all under ONE correlation chain.

Strategies. replace (the default) rolls every instance of the lane. canary=<n> rolls n instances first (the oldest), then holds until rollover continue rolls the rest or rollover abort returns the canaries to the source release. After continue, rollover rollback returns every instance. rollover finish closes a completed rollover and offers the source release for retirement — it prints the opschain admin agent-release retire command and never runs it.

blue-green restarts nothing: a green lane is brought up on the target release beside the serving lane and dispatch is flipped to it in one atomic write. Before anything starts the rollover checks the licence's agents headroom for the overlap — every instance connected now plus the green instances still to come must fit the limit — and refuses by name with the numbers (licence_headroom) when they do not. Then you start the green instances yourself (a second deployment, new state directories) from the target release with the green lane's name — opschain agent --lane <green> or OPSCHAIN_AGENT_LANE=<green>; the default green lane is <lane>-green, --green-lane names another. Each one enrols into the green lane and counts toward --size (default: the serving lane's live instance count); instances already up in the green lane on the target release count from the start. At size the rollover holds green_ready — the green lane serves nothing yet (a dispatch may name it explicitly to smoke-test it). rollover continue is the flip: the two lanes swap labels in one set-based write — the green instances now carry the serving lane's label and take every new dispatch, the old instances carry the green lane's name, serve nothing and finish their in-flight work (flipped). rollover rollback swaps them back the same way and closes the rollover (rolled_back; the green lane keeps its instances — stop them, or roll over again and they count at once). rollover finish retires the old lane: each old instance is drained, halted with a typed reason naming the rollover (stop the process) and its instance row retired, then the source release is offered for retirement as above. rollover abort closes a blue-green rollover before its flip. A relabelled instance keeps its label across a restart: a re-enrolment presenting the lane it enrolled with keeps the platform's label, one presenting a different lane is your relabel.

Drain modes. --drain is the default behaviour stated explicitly: the platform instructs the restart. --drain-only drains and reports; you restart the instances yourself (a process manager, a deployment), and the rollover completes as each one re-enrols from the release. An instance that comes back on a release the rollover did not expect stays drained.

Governed lanes. On an estate carrying the approval fabric, a rollover whose lane serves a governed environment — an environment the agent's trust grants reach carries a release_stage_floor at a governed rung of the ladder; with no floor in reach, the stable lane rolled to a release at the ladder's top rung — lands held in the same approval funnel a governed promotion enters (the shadow lane never writes and is never held); approvers resolve from --approver, else the configured agents.approvers (a governed rollover is never approver-less). Quorum completion starts it; rejection or the quorum TTL refuses it (warn:agent:rollover_refused). Without the fabric the rollover starts directly, audited.

Re-enrolment needs the registration token available to the restarted process (the token the agent was started with, or the environment the container start presents) — a restart from a release re-enrols the instance, it never resumes silently on the old release.

<agent> is the agent's member id, <project>/<code>, or a bare code when exactly one project holds it.

Subcommands

Subcommand	Purpose
continue	Release the rest of the lane after the canaries — opschain docs cli/admin-agent-rollover-continue.
abort	Return the canaries to the source release and close the rollover — opschain docs cli/admin-agent-rollover-abort.
rollback	Return every instance of the lane to the source release — opschain docs cli/admin-agent-rollover-rollback.
finish	Close a completed rollover (under blue-green: retire the old lane's instances) and offer the source release for retirement — opschain docs cli/admin-agent-rollover-finish.
show	The lane's open rollover (or one by id) with the lanes it concerns and which one dispatch serves — opschain docs cli/admin-agent-rollover-show.

Flags

Flag	Meaning
--to <name>@<version>	The target release (required).
--lane <lane>	The lane to roll: stable (default), shadow, canary or a label.
--strategy replace|canary=<n>|blue-green	replace rolls every instance of the lane; canary=<n> rolls n first and holds for continue / abort (canary alone means 1); blue-green brings a green lane up on the release beside the lane, continue flips dispatch, rollback flips back, finish retires the old lane.
--green-lane <lane>	blue-green: the lane brought up on the release beside the serving lane (default <lane>-green; must differ from the serving lane and from shadow).
--size <n>	blue-green: how many green-lane instances the flip waits for (default: the serving lane's live instance count).
--drain	Drain each instance and let the platform instruct its restart (the default, stated explicitly).
--drain-only	Drain each instance and report; you restart them — the rollover completes as they re-enrol from the release.
--approver <user>	Approver for a funnel-held rollover (repeatable; default: agents.approvers).
--reason <text>	Audited rollover reason.
--server <url>	Server base URL. Default: the active context, then OPSCHAIN_SERVER.
--auth-token <token>	Admin bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login for that server.

Output

rollover 01a1aecc-… of limebank/felix lane stable: felix@2.0.0 → felix@2.1.0 (canary=1), 2 instance(s) targeted, status rolling

A held rollover prints … is held for approval — approve or reject it through the approvals inbox. A blue-green rollover adds blue-green: 0 of 2 instance(s) up in the green lane stable-green; start the rest from felix@2.1.0 with --lane stable-green (or OPSCHAIN_AGENT_LANE=stable-green), then 'rollover continue' flips dispatch to them. -o json|yaml prints the rollover document (id, lane, strategy, green_lane, size, from_release, to_release, status, targets, canaries, restarted, returned, correlation_id, held).

Exit codes

Code	Meaning
0	The rollover started (or was held).
1	The server refused it: stage policy, a retired or revoked release, no live instance, the lane already on the release, a rollover already open, approver-less when governed; under blue-green also an unusable green lane or no licence headroom for the overlap.
2	Usage — no --to, both drain flags, a malformed --strategy, --green-lane / --size without --strategy blue-green, or no server / admin token resolvable.

Named errors

• --to is mandatory: the target release as <name>@<version> — exit 2.
• --strategy must be replace, canary[=<n>] or blue-green — exit 2.
• --green-lane and --size apply to --strategy blue-green only — exit 2.
• the green lane is not usable for this blue-green rollover: … — the green lane is the serving lane or shadow, or already holds live instances on another release; exit 1.
• the licence's agents limit leaves no headroom for the blue-green overlap: bringing <n> more instance(s) up in lane "<green>" would put <total> connected instances against the licence's agents limit of <limit> (<connected> connected now, headroom <headroom>) — … — exit 1.
• the release's stage does not satisfy the stage floor its scopes require — the stage policy, exit 1.
• agent release is retired: it accepts no new enrolment or rollover / agent release is revoked: … — exit 1.
• the lane holds no live instance to roll over — exit 1.
• a rollover of this agent's lane is already in progress: continue, abort, rollback or finish it first — exit 1.

See also

• opschain docs cli/admin-agent-instances — the instances and lanes.
• opschain docs cli/admin-agent-release-retire — the retirement the finish offers.
• opschain docs agent-releases — the release ladder the rollover moves between.