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"

Agent-led continuity upgrade

This is a decision guide, not a command recipe. Adapt paths and checks to the host in front of you.

1. Inspect the current CLI, daemon, nodes, and plugins with the helper.
2. Checkpoint active work and record the exact protected tmux/session census.
3. Run rig snapshot <rig-id> for each protected rig.
4. Create and verify the SQLite backup.
5. Build or stage the target runtime separately. Prove its version and source identity before touching the live daemon.
6. Run rig daemon stop. Verify both the listener and the identified daemon process are gone. If the command returns while either remains, stop: inspect identity and use the host's authorized recovery procedure. Do not blindly signal a PID.
7. Start the target with rig daemon start or the host's known wrapper. Verify daemon status, process path, listener, version, and database integrity.
8. Run the plugin refresh helper in plan mode. Apply safe writes only after the three roots and classifications make sense; resolve preserved paths one at a time when required.
9. Verify protected seats with rig ps --nodes -A --json, representative rig capture, and rig restore-check where applicable. -A is required: without it the node read is your CURRENT rig only, and a daemon upgrade protects seats across every rig on the host — so the narrow form reports success while seats outside your rig went unchecked.
10. Align wrappers only after deriving how that host owns them. Use its existing mechanism; this skill does not rewrite launchers.
11. Record the observed result, remaining local preservation decisions, and the exact rollback runtime and backup.
12. Read what changed in the new version, rig context get reference/whats-new.md, and tell your user anything in it that changes how they work.

Stop and hand back when

• a protected tmux session is missing before the upgrade;
• database integrity or backup verification fails;
• the running process or listener does not match the expected runtime;
• daemon stop reports success but the identified process or listener remains;
• the target cannot start against the existing database;
• plugin roots cannot be tied to a known ancestor and target;
• a required plugin path is classified as locally modified or deleted and the correct ownership decision is unclear;
• continuing would require rig down, destructive restore, credential changes, or broader authority than the operator has.

When stopping, report the last proven-good state, the first failed expectation, the exact evidence, and the smallest decision needed from the owner. Preserve live seats and the database unless recovery specifically requires otherwise.

Rollback is also agent-led

Prefer starting the previous known runtime against the still-valid database. Restore the database backup only when a migration or corruption finding requires it; a degraded projection alone is not proof that the database should be replaced. After rollback, repeat the same process, listener, database, plugin, and seat observations used during the forward path.