Loading
Use when an agent is preparing or performing an OpenRig CLI/daemon upgrade and must preserve live seats, verify each mutation, or reconcile managed plugin and skill files without overwriting local wor
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add mvschwarz/openrig --skill openrig-upgrade -a cursor -y
Use when an agent is preparing or performing an OpenRig CLI/daemon upgrade and must preserve live seats, verify each mutation, or reconcile managed plugin and skill files without overwriting local work.
Use when an agent is preparing or performing an OpenRig CLI/daemon upgrade and must preserve live seats, verify each mutation, or reconcile managed plugin and skill files without overwriting local work.
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.
Keep these planes separate:
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.
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.
For every step:
Let SKILL_DIR be the directory containing this SKILL.md. These scripts emit
JSON and do not decide the upgrade sequence.
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.
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.
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.
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"
This is a decision guide, not a command recipe. Adapt paths and checks to the host in front of you.
rig snapshot <rig-id> for each protected rig.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.rig daemon start or the host's known wrapper. Verify
daemon status, process path, listener, version, and database integrity.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.rig context get reference/whats-new.md,
and tell your user anything in it that changes how they work.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.
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.