OpenRig Upgrade Procedure

Upgrade OpenRig

An upgrade is an observed agent workflow, not a transaction hidden behind one command. Hosts differ, process state drifts, local plugin files accumulate, and the useful response to a failed step depends on what is still alive.

The agent owns the sequence. Stop after every mutation and observe the actual effect before choosing the next step. There is deliberately no end-to-end upgrade subcommand.

Safety model

Keep these planes separate:

• Seats normally live in tmux and can survive a daemon restart.
• The daemon, database, wrappers, and managed plugin projection are the control plane being changed.
• rig down tears down seats. It is not part of a continuity-preserving upgrade.

Before acting, name the rigs and seats whose continuity matters. On a production host, use the host's normal operator ceremony. On a recovery-friendly build VM, the orchestrator may adopt a tested runtime directly, but still observes each step and stops on unexplained drift.

When recovery crosses an instance boundary

Before either lane changes runtime state, record one host-qualified executor and explicitly select the queue store that owns the recovery ruling. State whether the original owner continues, waits, or transfers; an open obligation in another store is not exclusive custody of this ruling. If the original store is down, retain its owner's disposition in the surviving ruling and communicate it to that owner before a competing executor acts.

A refused claim means reconcile ownership with the ruling owner before any further runtime action; it does not authorize continuing under a separate older row. A return names the full executor address and deliberately selected store. Read the resulting row there, including source, destination, body, and the original owner's disposition, before resuming. Receipt creation alone does not establish that a waiting lane received or accepted the transfer.

The loop

For every step:

1. Inspect. Derive current facts from the live host.
2. Decide. Choose one bounded mutation and state its expected effect.
3. Act once. Do not bundle the next mutation with it.
4. Observe. Check the process, listener, database, plugin, and seat surfaces that the step could have changed.
5. Continue, adapt, or stop. A failed expectation is information for the agent, not permission for a blind retry.

Bounded helpers

Let SKILL_DIR be the directory containing this SKILL.md. These scripts emit JSON and do not decide the upgrade sequence.

Inspect current facts

node "$SKILL_DIR/scripts/inspect-upgrade.mjs"

This asks the installed rig for its version, daemon status, node inventory, and plugin inventory. A missing surface remains visible with a suggested next probe. ready: false means the agent must resolve or consciously bound the gap; it does not mean the script should mutate anything.

Back up SQLite

Take continuity snapshots first:

rig snapshot <rig-id>
node "$SKILL_DIR/scripts/backup-sqlite.mjs" \
  --source "$OPENRIG_HOME/openrig.sqlite" \
  --destination "/safe/path/openrig-before-upgrade.sqlite"

The helper refuses to overwrite a destination, uses SQLite's backup operation, and verifies the backup with PRAGMA integrity_check. It does not stop the daemon or restore a database.

Plan or apply safe managed-plugin refreshes

Plugin trees may contain skills as well as hooks and metadata. Compare the last packaged ancestor, the target package, and the live installed tree:

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>"

Review the sorted decisions. To apply only refresh-safe and add-safe files:

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>" \
  --apply-safe

The helper never deletes a live file and never overwrites a local modification. Local deletions, live-only files, target removals, and ambiguous types are reported for the agent to resolve. Re-run the plan after any manual resolution.

Migrate a pre-0.5.9 instance layout

Version 0.5.9 puts context-usage telemetry in $OPENRIG_HOME/state/context-usage, provider telemetry in state/provider-usage, the addressable library under context/, and the default System World at context/system/system-world.yaml. Existing 0.5.8 homes cross that boundary through an Agent-Operated Migration: the target runtime reads canonical-first with legacy-fallback while all new writes use the canonical state roots. An explicitly configured custom context-library root stays stable throughout activation.

The helper supplies bounded, inspectable operations. The agent owns their sequence and the target-runtime activation between them. With an exact protected preimage path, first inspect and then prepare canonical directories, the default System World, and a config pin to the existing library. Preparation does not copy telemetry, rewrite live collector settings, or run lifecycle actions:

--help prints the phase grammar without inventorying the instance. With no phase flag the helper intentionally runs the read-only plan; unknown options fail nonzero before plan or mutation.

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME"

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-state \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before"

Activate the exact target runtime using the ordinary upgrade workflow. Then wait until every bounded post-apply legacy tail is followed by newer paired new-root samples for that same seat. This proves temporal convergence without blanket process replacement; a later legacy write remains a hard stop. Capture the verification JSON; copied old sidecars are not evidence:

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --verify \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  > /safe/path/layout-0.5.9-verify.json

Only a successful receipt authorizes the separately invoked non-destructive finalizer. It copies an unconfigured legacy library into the canonical root without overwriting anything; a custom context-library root remains stable:

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-library \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  --verification /safe/path/layout-0.5.9-verify.json

Stop on every reported issue: malformed or foreign telemetry, a reserved-path conflict, a library collision, config drift, resumed legacy writes, byte drift, or a missing fresh dual sample all require the named repair before continuing. Verification binds the exact accepted tail bytes to their paired-newer samples; the finalizer revalidates them immediately before switching config. The helper never removes the legacy telemetry or library. Their later retirement is a separate agent decision after stable runtime, writer, reader, and recovery proof. It does not stop/start the daemon, launch a seat, touch the database, or decide whether the upgrade proceeds.

To recover, restore the prior runtime as the agent-led workflow requires, then reverse only helper-owned config, System World, empty-directory, and copied library effects. Real state samples and both legacy recovery sources remain for inspection:

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --rollback "$OPENRIG_HOME/backups/layout-0.5.9-before"