@openrig/cli 0.5.7 → 0.5.8

package/daemon/context-packs/skills/core/openrig-herdr/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-herdr"
-version: "0.5.7"
+version: "0.5.8"
 taxonomy: "skills"
 purpose: "Use when opening OpenRig fleet terminals as a herdr wall — turning a rig, pod, mission, slice, or saved view into live interactive agent tiles via `rig terminal`, watching another rig read-only, or driving herdr on an agent's request (\"open all my rigs + a mission as views\"). Covers the `rig terminal open|views|status` verbs, the honest-partial/degrade reading of the result, the read-only-by-construction rail for cross-rig views, scroll/copy out of the box, and the same-size-only duplicate-pane "
 files:

package/daemon/context-packs/skills/core/openrig-skills/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-skills"
-version: "0.5.7"
+version: "0.5.8"
 taxonomy: "skills"
 purpose: "Use when you're operating OpenRig and need the right skill or context for fleet recovery, seat handover, new-seat orientation, a watchdog wake, cross-host reach to an agent on another machine, rig packaging, an OpenRig upgrade, systematic debugging, queue triage, or implementation planning; also use when you don't know what applies or nothing is projected on cold boot."
 files:

package/daemon/context-packs/skills/core/openrig-upgrade/SKILL.md

@@ -1,404 +1,169 @@
 ---
 name: openrig-upgrade
-description: Use when upgrading the OpenRig CLI/daemon on a host with running rigs, especially when preserving tmux-backed agent sessions through a daemon restart or documenting hot-upgrade SOP evidence.
+description: 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.
 metadata:
   cli_surfaces_referenced:
     - capture
-    - daemon adopt-state
     - daemon start
     - daemon status
     - daemon stop
-    - down
+    - plugin list
     - ps
     - restore-check
     - snapshot
-    - up
-    - upgrade backup
-    - upgrade preflight
-    - upgrade promote-runtime
-    - upgrade verify
     - version
   openrig:
     stage: factory-approved
     sibling_skills:
       - openrig-user
       - openrig-operator
-      - openrig-builder
-      - openrig-architect
       - forming-an-openrig-mental-model
-      - ai-dev-workflows
 ---
 
-# OpenRig Upgrade
+# Upgrade OpenRig
 
-## Core Principle
+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.
 
-OpenRig has two different failure domains:
+**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.
 
-- **Agent process plane:** Claude/Codex/terminal seats running inside tmux.
-- **Management plane:** the OpenRig daemon, CLI, SQLite DB, transcripts, node inventory,
-  send/capture APIs, restore metadata, and migrations.
+## Safety model
 
-A hot daemon upgrade is possible when the continuity seats remain alive in tmux and
-the new daemon restarts against the same DB and transcript root. Do not run
-`rig down` on continuity rigs unless the goal is a disruptive restore test; `rig down`
-kills OpenRig-launched tmux sessions.
+Keep these planes separate:
 
-## Preferred Live-Cutover Operator Mode
+- 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.
 
-For live production daemon cutovers, prefer an **out-of-band upgrade operator**:
-a temporary host-local tmux seat outside the managed OpenRig topology, spawned
-from the lifecycle/runtime-upgrade agent's current mental model.
+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.
 
-Why: the managed rig stays in the agent process plane while a disposable sidecar
-mutates the management plane. The sidecar inherits enough context to avoid a
-cold handoff, but it is not inside the failure domain it is modifying.
+## The loop
 
-Use this when all are true:
+For every step:
 
-- the upgrade mutates the live daemon, CLI wrapper, DB, runtime worktree, tmux
-  lifecycle, or active control-plane truth;
-- continuity seats should keep working during the upgrade;
-- a lifecycle/runtime-upgrade seat has already prepared the packet or owns the
-  needed context;
-- the human has granted an `operator auto window`.
+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.
 
-In this SOP, `operator auto window` means a bounded operator-authorized upgrade lane. It does not
-mean standing Codex `auto_review`, `--full-auto`, or approval-bypass mode. Use
-`security-and-consequence-boundary-policy` skill for the current
-security and consequence-boundary policy.
+## Bounded helpers
 
-Do not use this pattern as a standing orchestration seat. The sidecar exists for
-one cutover and then closes after handback.
+Let `SKILL_DIR` be the directory containing this `SKILL.md`. These scripts emit
+JSON and do not decide the upgrade sequence.
 
-### Sidecar Contract
+### Inspect current facts
 
-The in-rig lifecycle/runtime-upgrade seat owns packet preparation and final
-interpretation. The out-of-band sidecar owns only execution inside the approved
-window.
-
-Sidecar starter prompt shape:
-
-```text
-You are the host-local OpenRig runtime upgrade operator, outside the managed rig
-topology. Execute the approved daemon-only cutover only after explicit human
-approval. First read the upgrade preflight artifact and runtime-upgrade
-decision. Prove you are outside the topology before mutation. Never run rig
-down. Preserve tmux topology. Stop/start only the daemon, verify protected rigs,
-write cutover evidence, unblock downstream artifacts only when the blocker is
-truly closed, and rollback to <previous-wrapper-or-commit> if needed.
+```bash
+node "$SKILL_DIR/scripts/inspect-upgrade.mjs"
 ```
 
-Required handback:
-
-- write the live cutover evidence under the lifecycle evidence shelf;
-- include proof that the sidecar was outside the topology/failure domain it
-  mutated;
-- update any blocked downstream dogfood/runtime task only when the blocking
-  condition is truly closed;
-- preserve caveats as downstream material instead of using them to reopen a
-  closed cutover gate;
-- report back to the in-rig lifecycle/runtime-upgrade seat or orch surface with
-  daemon provenance, topology verification, caveats, rollback state, and one
-  compact paragraph of operator judgment about ambiguous choices;
-- close the sidecar after the original lifecycle owner has absorbed the result.
-
-Stop conditions for the sidecar:
-
-- preflight or runtime-upgrade decision is missing;
-- human approval is absent or narrower than the requested cutover;
-- protected topology is already degraded beyond the packet's expected caveats;
-- target runtime cannot be verified by process path, port listener, and command
-  evidence;
-- any step would require `rig down` or destructive DB restore without a new
-  explicit human decision.
-
-Generic primitive: this upgrade specialization composes over the
-`sidecar-operator` skill (the underlying out-of-band-operator pattern;
-this skill is the upgrade-specific specialization).
-
-## What Changed On 2026-04-27
-
-Initial belief:
-
-- All rigs had to be down before daemon restart.
-- Live upgrade was research-gated because DB migrations might break session/node
-  state while sessions were running.
-- A parallel isolated daemon/adoption path looked necessary before production use.
+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.
 
-Observed result:
-
-- A daemon-only hot cutover preserved the live `example-seat` tmux
-  sessions.
-- The old daemon was stopped without running `rig down`.
-- The new source-pinned daemon started against the same production DB.
-- `rig ps --nodes --json`, `rig capture`, and `rig restore-check` could inspect the
-  still-running continuity seats after restart.
+### Back up SQLite
 
-The simpler model is now preferred for tmux-backed continuity rigs: snapshot and
-back up state, stop only the daemon, start the new daemon, then verify that live
-sessions are still observable and manageable.
-
-## Proven Hot Path
-
-Use this as the canonical first-choice workflow for a host where continuity rigs
-are tmux-backed and the operator wants non-disruptive daemon upgrade.
-
-0. **Spawn the out-of-band operator when live cutover is required.**
-   The sidecar must be host-local and outside the managed topology being
-   upgraded. Keep the lifecycle/runtime-upgrade owner inside the rig so it can
-   continue to observe, ask questions, and absorb the handback.
-
-1. **Choose continuity targets.**
-   Name the exact rigs that must remain live. Everything else is source material.
-   Do not let "nice to resume later" rigs expand the success criteria.
-
-2. **Freeze active work.**
-   Get continuity seats to a stable/idle checkpoint. Record resume commands if
-   available.
-
-3. **Inventory with filters.**
-   Do not dump full `rig ps` output on this host. Use filtered JSON:
-
-   ```bash
-   rig ps --nodes --json \
-     | jq -r 'map(select(.rigName=="<rig>")) | sort_by(.canonicalSessionName)[] | "\(.canonicalSessionName) \(.sessionStatus) \(.startupStatus) \(.resumeToken // "none")"'
-   ```
-
-4. **Take a non-destructive snapshot of each continuity rig.**
-   This records rollback/recovery metadata without killing tmux sessions:
-
-   ```bash
-   rig snapshot <rigId>
-   ```
-
-   Verify the snapshot payload in SQLite has the expected nodes, sessions,
-   checkpoints, and resume tokens.
-
-5. **Create a post-snapshot SQLite backup.**
-   Use SQLite's online backup API while the daemon is live. Then run
-   `PRAGMA integrity_check` on the backup and verify it contains the continuity
-   snapshot.
-
-6. **Prepare a clean runtime artifact.**
-   Prefer a dedicated clean source worktree pinned to a commit:
-
-   ```bash
-   git worktree add --detach /path/to/openrig-runtime-<shortsha> <commit>
-   cd /path/to/openrig-runtime-<shortsha>
-   PATH=/path/to/node22/bin:$PATH npm ci
-   PATH=/path/to/node22/bin:$PATH npm run build
-   ```
-
-   Use even/LTS Node. The 2026-04-27 upgrade used Node `v22.22.1`.
-
-7. **Stop only the daemon.**
-   First try:
-
-   ```bash
-   rig daemon stop
-   ```
-
-   If the daemon state file is missing but the PID is known and verified as the
-   OpenRig daemon, gracefully terminate that PID:
-
-   ```bash
-   kill -TERM <daemonPid>
-   ```
-
-   Do not use `kill -9` unless recovering from a wedged process with human
-   approval. Do not run `rig down` on continuity rigs.
-
-8. **Start the pinned daemon against the same production DB.**
-
-   ```bash
-   PATH=/path/to/node22/bin:$PATH \
-     node packages/cli/dist/index.js daemon start \
-       --port 7433 \
-       --host 127.0.0.1 \
-       --db ~/.openrig/openrig.sqlite
-   ```
-
-9. **Verify management continuity.**
-   Required checks:
-
-   ```bash
-   rig daemon status
-   lsof -nP -iTCP:7433 -sTCP:LISTEN
-   rig ps --nodes --json | jq -r 'map(select(.rigName=="<rig>")) | ...'
-   rig capture --rig <rig> --lines 1 --json
-   rig restore-check --rig <rig>
-   ```
-
-   Success means the daemon is healthy, continuity sessions remain running/ready,
-   capture works, transcripts are present, and `restore-check` reports no red
-   blockers.
-
-10. **Align the default CLI with the new daemon.**
-    If `rig` is a wrapper, make sure it delegates to the new CLI.
-
-11. **Write evidence and hand back.**
-    The sidecar writes a cutover evidence packet with daemon provenance,
-    protected topology counts, representative capture/restore checks, smoke
-    results, caveats, and rollback state. Then it notifies the original in-rig
-    lifecycle/runtime-upgrade owner. Do not rely on chat as the only proof.
-
-## Proof Point: Daemon-Only Hot Cutover
-
-A clean source runtime on an LTS Node version replaced the old daemon while one
-tmux-backed continuity rig stayed live. The operator took a post-snapshot online
-database backup, verified its integrity, stopped only the daemon, started the
-new runtime against the same database, and confirmed that every protected seat
-remained running and ready with no red restore blockers.
-
-Important caveat: this proves hot daemon cutover for the tested tmux-backed
-Claude runtime shape. It does not prove that arbitrary migrations,
-non-tmux runtimes, service-backed rigs, or dead sessions can be recovered without
-separate testing.
-
-## Proof Point: Out-of-Band Sidecar Cutover
-
-A lifecycle owner prepared the decision and preflight artifacts, then spawned a
-host-local tmux sidecar outside the managed topology. The sidecar stopped only
-the daemon, used a verified graceful PID fallback when daemon state was stale,
-started the pinned runtime, aligned the default wrapper, verified the protected
-topology, ran targeted smoke checks, retained cutover evidence, and handed the
-result back while delivery continued.
-
-Important caveat: live `rig up --plan --json` accepted valid `starter_ref`
-specs and rejected forbidden compositions, but plan-mode output did not emit the
-`resolve_starter.detail.starterContent` stage expected by the Dogfood proof bar.
-This is a product/dogfood caveat, not an upgrade failure.
-
-## Brittle Edges Observed On 2026-04-27
-
-Operator lessons from the daemon upgrade:
-
-- `rig down` kills OpenRig-launched tmux sessions. Do not use it as a snapshot
-  primitive when resumability depends on keeping sessions alive.
-- Old daemon/CLI combinations can be partially functional even when newer health
-  checks fail. A `/healthz` mismatch blocked `rig down --snapshot` even though
-  other daemon APIs still worked.
-- `rig daemon stop` can fail when the daemon state file is missing. Operators
-  need a verified PID fallback, but the product should reconcile daemon state
-  automatically.
-- If the sidecar has an operator auto window and `rig daemon stop` refuses only
-  because state is stale, a verified graceful PID termination is acceptable:
-  identify the daemon PID, verify its runtime path, send graceful `TERM`, and
-  verify the port is gone before starting the target daemon.
-- CLI and daemon provenance can drift. Repointing or verifying the default
-  `rig` wrapper is part of the upgrade, not an afterthought.
-- Raw `rig ps` output can be noisy. Use filtered JSON until the product
-  has compact first-class inventory views.
-- Snapshot and backup verification is too manual. The SOP currently depends on
-  checking snapshot rows, resume tokens, SQLite backups, and integrity by hand.
-
-## Disruptive Restore Path
-
-Use disruptive restore when the goal is to test recovery from killed sessions, or
-when hot upgrade is blocked by incompatible migrations or corrupted management
-state.
+Take continuity snapshots first:
 
 ```bash
-rig snapshot <rigId>
-rig down <rigId>
-# upgrade daemon/CLI
-rig up <rigName>
-rig restore-check --rig <rigName>
+rig snapshot <rig-id>
+node "$SKILL_DIR/scripts/backup-sqlite.mjs" \
+  --source "$OPENRIG_HOME/openrig.sqlite" \
+  --destination "/safe/path/openrig-before-upgrade.sqlite"
 ```
 
-Expected restore results:
-
-| Result | Meaning | Action |
-|---|---|---|
-| `fully_restored` | All nodes resumed or rebuilt | Resume normal work |
-| `partially_restored` | Some nodes succeeded, some failed | Inspect failed nodes and relaunch manually |
-| `failed` | Zero nodes restored | Check daemon logs, snapshot integrity, provider tokens |
-| `not_attempted` | Pre-restore blockers | Fix blockers before retrying |
-
-Do not confuse this path with hot upgrade. `rig down` is intentionally
-disruptive.
-
-## Stop Conditions
+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.
 
-Do not proceed with hot upgrade if:
+### Plan or apply safe managed-plugin refreshes
 
-- continuity targets are mid-task and cannot checkpoint;
-- continuity target tmux sessions are missing before upgrade;
-- no verified DB backup exists after continuity snapshots;
-- the target runtime cannot build under an even/LTS Node version;
-- the daemon migration plan is known to rewrite session/binding semantics in a
-  way that has not been tested;
-- disk space or DB integrity checks fail;
-- the operator cannot identify the current daemon PID and runtime source.
+Plugin trees may contain skills as well as hooks and metadata. Compare the last
+packaged ancestor, the target package, and the live installed tree:
 
-## Rollback
-
-Rollback means restoring the previous daemon runtime and, if necessary, the DB
-backup.
-
-For source runtime:
-
-1. Stop the new daemon.
-2. Start the previous runtime or npm/global daemon.
-3. Verify `/healthz`, filtered continuity inventory, and `rig capture`.
-4. Restore the DB backup only if migration or DB corruption is confirmed. Do not
-   replace the DB just because continuity sessions are still live but management
-   projection is degraded.
+```bash
+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>"
+```
 
-For npm runtime:
+Review the sorted decisions. To apply only `refresh-safe` and `add-safe` files:
 
 ```bash
-npm install -g @openrig/cli@<previous-version>
-rig daemon stop
-rig daemon start
+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
 ```
 
-## Roadmap: Better Hot Upgrades
-
-The product should make the proven manual path boring and explicit.
-
-Needed product surfaces:
-
-- `rig upgrade preflight`:
-  daemon PID/runtime source, CLI source, DB path, migration plan, active rigs,
-  continuity targets, tmux liveness, disk space, DB integrity, backup target,
-  and rollback runtime.
-- `rig daemon adopt-state` or equivalent:
-  recover a healthy daemon on a port when `daemon.json` is missing.
-- `rig upgrade backup`:
-  online SQLite backup plus integrity and snapshot-presence verification.
-- `rig upgrade promote-runtime <commit|artifact>`:
-  start from a clean worktree or packaged artifact under an even/LTS Node.
-- `rig upgrade verify --rig <name>`:
-  filtered inventory, capture, transcript, restore-check, and honest continuity
-  classification.
-- CLI/daemon provenance:
-  `rig version --json` should report CLI path, daemon path, commit/package
-  version, Node version, DB path, and started-at.
-- Wrapper alignment:
-  the default `rig` wrapper should clearly show which real CLI it delegates to.
-- Compact inventory:
-  first-class `rig ps --rig <name> --nodes --compact` or equivalent, so
-  operators do not need ad hoc `jq` for routine safety checks.
-
-Research still needed:
-
-1. Migration-bearing hot upgrade on a throwaway rig.
-2. Hot upgrade with non-critical live Codex seats.
-3. Hot upgrade with service-backed rigs.
-4. Adoption/reconciliation when daemon DB says sessions are running but tmux has
-   partially drifted.
-5. Automated rollback on daemon startup failure or migration failure.
-
-## Operator Summary
-
-Hot upgrade rule:
-
-**Snapshot continuity rigs, back up the DB, stop only the daemon, start the new
-daemon against the same DB, then verify live tmux sessions through filtered
-management surfaces.**
-
-Disruptive restore rule:
-
-**Use `rig down` only when testing or accepting session teardown.**
+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.
+
+## 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.
+
+## 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.

package/daemon/context-packs/skills/core/openrig-upgrade/manifest.yaml

@@ -1,10 +1,16 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-upgrade"
-version: "0.5.7"
+version: "0.5.8"
 taxonomy: "skills"
-purpose: "Use when upgrading the OpenRig CLI/daemon on a host with running rigs, especially when preserving tmux-backed agent sessions through a daemon restart or documenting hot-upgrade SOP evidence."
+purpose: "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."
 files:
   - path: "SKILL.md"
     role: "instruction"
-    summary: "Use when upgrading the OpenRig CLI/daemon on a host with running rigs, especially when preserving tmux-backed agent sessions through a daemon restart or documenting hot-upgrade SOP evidence."
+    summary: "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."
+  - path: "scripts/backup-sqlite.mjs"
+    role: "reference"
+  - path: "scripts/inspect-upgrade.mjs"
+    role: "reference"
+  - path: "scripts/refresh-managed-plugin.mjs"
+    role: "reference"

package/daemon/context-packs/skills/core/openrig-upgrade/scripts/backup-sqlite.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+function argument(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? undefined : process.argv[index + 1];
+}
+
+function fail(message, next) {
+  process.stderr.write(`${JSON.stringify({ ok: false, error: message, next }, null, 2)}\n`);
+  process.exit(1);
+}
+
+const source = argument("--source");
+const destination = argument("--destination");
+if (!source || !destination) {
+  fail("--source and --destination are required", "choose an existing OpenRig SQLite database and a new backup path");
+}
+
+const sourcePath = path.resolve(source);
+const destinationPath = path.resolve(destination);
+if (!fs.existsSync(sourcePath) || !fs.statSync(sourcePath).isFile()) {
+  fail(`source database is not a regular file: ${sourcePath}`, "derive the live database path from daemon status before retrying");
+}
+if (fs.existsSync(destinationPath)) {
+  fail(`destination already exists: ${destinationPath}`, "choose a new path; this helper never overwrites a backup");
+}
+if (destinationPath.includes("'") || destinationPath.includes("\n")) {
+  fail("destination contains a quote or newline unsupported by the sqlite3 backup command", "choose a simple filesystem path");
+}
+
+fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+const sqlite = process.env.OPENRIG_SQLITE_BIN || "sqlite3";
+const backup = spawnSync(sqlite, [sourcePath, `.backup '${destinationPath}'`], { encoding: "utf8" });
+if (backup.status !== 0) {
+  fs.rmSync(destinationPath, { force: true });
+  fail(
+    backup.stderr?.trim() || backup.stdout?.trim() || backup.error?.message || "sqlite3 backup failed",
+    `run ${sqlite} against the source directly, resolve locking/path/tooling errors, then choose a fresh destination`,
+  );
+}
+
+const check = spawnSync(sqlite, [destinationPath, "PRAGMA integrity_check;"], { encoding: "utf8" });
+const integrity = check.stdout?.trim();
+if (check.status !== 0 || integrity !== "ok") {
+  fail(
+    check.stderr?.trim() || `backup integrity result was ${JSON.stringify(integrity)}`,
+    "preserve the failed backup for diagnosis only; do not use it for rollback",
+  );
+}
+
+process.stdout.write(`${JSON.stringify({
+  schema: "openrig-sqlite-backup/v1",
+  ok: true,
+  source: sourcePath,
+  destination: destinationPath,
+  bytes: fs.statSync(destinationPath).size,
+  integrity,
+}, null, 2)}\n`);