@openrig/cli 0.4.6 → 0.4.7

package/daemon/specs/agents/shared/skills/core/human-in-the-loop/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: human-in-the-loop
+description: Use when classifying a slice closeout (auto-continue / human gate / park), routing a real decision to a human, or designing a human queue/dashboard surface. Treats humans as durable network participants with attention surfaces, queues, and decision records — escalation lands as a durable attention item, not a chat message. Approval is NOT required for every clean closeout; the default RSI conveyor continues unless an explicit human gate is reached.
+metadata:
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - queue-handoff
+      - workflow-runtime
+      - watchdog
+      - alignment-trace
+      - looping-workflows
+      - intake-routing
+      - attention-queue
+      - dispatching-parallel-agents
+      - subagent-driven-development
+      - control-plane-capabilities
+      - status-not-chat-orchestrator
+      - control-plane-queue
+      - control-plane-watchdog
+      - control-plane-workflows
+      - control-plane-delivery-loop
+      - control-plane-rollout-manager
+---
+
+# Human In The Loop
+
+The primitive that treats humans as **durable network participants** —
+attention surfaces, queues, decision records, routing semantics — not
+as ad-hoc chat receivers.
+
+**Autonomy is not the absence of humans; it is knowing when human
+judgment is needed and making that handoff crisp.**
+
+## Use this when
+
+- A slice closeout needs classifying: auto-continue, human gate, or park
+- A real decision needs to land in front of a human (usage limits, provider auth, roadmap tradeoff, product-intent ambiguity)
+- Designing a human queue/dashboard surface
+- Returning a hot potato to orchestration after human approval
+
+## Don't use this when
+
+- The slice closeout is clean and `PROGRESS.md` already names the next safe slice. **Default RSI conveyor continues; do NOT manufacture a human gate.**
+- The escalation is just a status update. Humans are participants for *decisions*, not narration.
+- The next owner is another agent. Use queue-handoff, not human-in-the-loop.
+
+## The 3-class closeout classification
+
+In a productized daemon-backed version, closeout classifies the next
+step BEFORE touching the human queue:
+
+| Class | When | Action |
+|---|---|---|
+| **auto-continue** | Slice closes cleanly, next named slice in workstream plan | Mark closed; create next-owner qitem from plan |
+| **human gate** | Genuine decision needed (usage limits, provider auth, product-intent ambiguity, roadmap tradeoff) | Create human queue item with proof + decision text + recommended default + action outcomes |
+| **park** | Intentionally stop the conveyor (e.g., waiting on external) | Stop with reason + resumption path |
+
+## Failure modes (5)
+
+1. **Human decision needed, but the rig only mentions it in chat.** Decisions belong as durable attention items, not chat messages.
+2. **Human queue item lacks enough plain-English context for a decision.** Include proof + decision text + recommended default + action outcomes.
+3. **Human response updates a file but does not wake the next owner.** Approval should return the hot potato; feedback should create the next durable qitem.
+4. **The dashboard shows too much raw rig state and hides the actual decision queue.** Decision queue is the primary surface; rig state is secondary.
+5. **A clean closeout is parked on the human even though `PROGRESS.md` already names the next safe slice.** Don't manufacture human gates.
+
+## Proof standard (both paths)
+
+A trustworthy human-in-the-loop system proves both directions:
+
+- **Blocking gate path**: real item routed to human → human decision recorded through UI → resulting hot-potato handoff wakes correct next owner
+- **Non-blocking closeout path**: proof inspectable by human, but orchestrator continues to next named slice without manufacturing a human gate
+
+A primitive that only wakes humans is not trustworthy. It must also know when NOT to.
+
+## Product shape (SHIPPED — Mission Control, PL-005)
+
+This surface has shipped as **Mission Control** (product UI, `/mission-control`
+route; actions via `POST /api/mission-control/action`). The seven verbs the
+human acts with:
+- **approve** (returns the hot potato to orchestration or the chosen owner)
+- **deny** (reject the item)
+- **route** (send to a different owner)
+- **annotate** (add context without action)
+- **hold** (intentional pause with reason)
+- **drop** (mark not-actionable)
+- **handoff** (hand to a specific next owner — creates the next durable qitem)
+
+**Approval returns the hot potato to orchestration or the chosen owner;
+feedback creates the next durable qitem rather than only mutating the source
+queue file** — enforced by the shipped verbs (handoff/route create qitems).
+See `docs/as-built/architecture/mission-control.md`.
+
+## Long-term shape
+
+Likely needs **multiple humans with different scopes**, not a singleton
+human attention feed. Different humans own different decision
+domains; queue items route by scope.
+
+## See also
+
+- `queue-handoff` skill — durable handoff via queue items; human-in-the-loop is the human-side complement
+- `watchdog` skill — when to wake (humans included) vs no-op
+- `looping-workflows` (convention) — the looping-workflows convention covers loop closeouts; human-in-the-loop is the escape hatch

package/daemon/specs/agents/shared/skills/core/openrig-architect/SKILL.md

@@ -1,18 +1,28 @@
 ---
 name: openrig-architect
-description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (work in the openrig product repo); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
+description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
 metadata:
+  cli_surfaces_referenced:
+    - agent validate
+    - capture
+    - daemon start
+    - ps
+    - send
+    - spec validate
+    - specs ls
+    - up
+    - whoami
   openrig:
     stage: factory-approved
-    last_verified: "2026-05-04"
-    distribution_scope: product-bound
-    source_evidence: |
-      Bootstrap skill — NPM install lands this in personal homes (~/.claude/skills/, ~/.agents/skills/) for users authoring their own rigs.
     sibling_skills:
       - openrig-user
       - openrig-operator
+      - openrig-builder
+      - openrig-upgrade
       - forming-an-openrig-mental-model
-    transfer_test: pending
+      - ai-dev-workflows
+    notes: |
+      Description was already correct (starts with "Use when..."; lists specific authoring triggers including the diagnose-bad-rig case). Final sentence ("Covers the full authoring lifecycle from user intent to validated, launchable rig.") is workflow-summary-adjacent; on next iteration, consider trimming. For factory-adoption cycle, kept as-is to match product source-of-truth.
 ---
 
 # OpenRig Architect
@@ -47,8 +57,13 @@ Load these before starting any design work. The quality of your output depends o
 
 **Read if present on this host:**
 
-4. **Host-level doctrine file** (if your team maintains one — e.g., a HOST-TOPOLOGY doc that defines canonical rig classes, context-sharing patterns, and authoring SOPs for high-stakes rigs). If present, it supersedes the baseline process below for complex or high-stakes rigs (≥4 members, HA, managed-app, or shared/copied). Solo operators and small/focused rigs use the baseline below directly.
-5. **Agent-facing software design principles** if your rig ships a new CLI, service, or managed app that agents will operate. Treat the operating surface as a context-engineering problem: every error message and help text gives the agent information to act on.
+4. **Host-level doctrine** in your host's topology doc, if it keeps one. If this file exists, it supersedes the baseline process below for complex or high-stakes rigs. Specifically:
+   - §3 defines the canonical rig classes (kernel, project, ephemeral, infra-build, managed-app). Classify before designing.
+   - §4 defines context-sharing patterns (pods as context domains, pair pattern, HA via mental-model-ha skill + substrate session logs, terminal nodes as common-room, chatroom/substrate/transcripts/Corpus).
+   - **§7 is the canonical 12-step rig-spec authoring SOP for high-stakes rigs — use it instead of the baseline "Design Process" below when the rig is ≥4 members, uses HA, is a managed-app, or will be shared/copied.** The baseline below still applies to small/focused rigs.
+   - §10 contains the host's bootstrap sequence so you know where your new rig fits.
+   - §12 has the naming canon and vocabulary mapping to shipped terms.
+5. **`building-agent-software` skill** if available in your skill catalog. Design principles for agent-facing tools and surfaces. Relevant when your rig ships a new CLI, service, or managed app.
 
 **Load as needed:**
 - Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
@@ -231,6 +246,8 @@ rig spec validate rig.yaml
 rig agent validate agents/my-agent/agent.yaml
 ```
 
+Then run `rig spec audit rig.yaml` for advisory checks such as stale seat references and other cross-file drift that schema validation cannot detect.
+
 If validation fails, fix the errors. Do not try to launch an invalid spec — it will fail with a less helpful error.
 
 ## Diagnosis: When Things Go Wrong

package/daemon/specs/agents/shared/skills/core/openrig-cmux/SKILL.md

@@ -9,11 +9,6 @@ description: >
 metadata:
   openrig:
     stage: candidate
-    distribution_scope: product-bound
-    source_evidence: |
-      cmux is OpenRig's shipped terminal provider generalized onto `rig terminal <provider>` —
-      best-effort, not proof-gated. Authored clean-room.
-    transfer_test: pending
     sibling_skills:
       - openrig-herdr
       - openrig-user

package/daemon/specs/agents/shared/skills/core/openrig-herdr/SKILL.md

@@ -10,11 +10,6 @@ description: >
 metadata:
   openrig:
     stage: candidate
-    distribution_scope: product-bound
-    source_evidence: |
-      Empirical herdr 0.7.1 hands-on findings + the ratified implementation PRD. Authored
-      clean-room (patterns only, no herdr source text; AGPL arm's-length).
-    transfer_test: pending
     sibling_skills:
       - openrig-cmux
       - openrig-user
@@ -51,7 +46,7 @@ An agent asked "open all my rigs plus a mission as views" runs one `open` per ta
 ```bash
 rig terminal open acme-web                     # a whole rig, live agents as tiles
 rig terminal open mission:site-relaunch        # exactly the agents working the mission
-rig terminal open slice:02-search-filters      # the agents working one slice
+rig terminal open slice:search-filters      # the agents working one slice
 ```
 
 No hand-listing of seats: the mission/slice membership is derived from live topology at open time.

package/daemon/specs/agents/shared/skills/core/openrig-upgrade/SKILL.md

@@ -0,0 +1,460 @@
+---
+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.
+metadata:
+  cli_surfaces_referenced:
+    - capture
+    - daemon adopt-state
+    - daemon start
+    - daemon status
+    - daemon stop
+    - down
+    - 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
+
+## Core Principle
+
+OpenRig has two different failure domains:
+
+- **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.
+
+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.
+
+## Preferred Live-Cutover Operator Mode
+
+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.
+
+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.
+
+Use this when all are true:
+
+- 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`.
+
+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.
+
+Do not use this pattern as a standing orchestration seat. The sidecar exists for
+one cutover and then closes after handback.
+
+### Sidecar Contract
+
+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.
+```
+
+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.
+
+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 Velocity seats after restart.
+
+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. On the
+    2026-04-27 host this meant repointing the rigx real CLI via
+    `~/.openrig/bin/rig-real-17812d5`.
+
+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.
+
+## 2026-04-27 Proof Point
+
+Continuity target:
+
+- `example-seat`
+
+Pinned daemon:
+
+- commit `17812d5d3bfe53dfdc5e202b1da3e8c91e2f4e54`
+- subject `feat(agents): make runtime config spec-driven`
+- committed `2026-04-26T18:30:08-07:00`
+- runtime worktree `~/code/projects/openrig-runtime-17812d5`
+
+Evidence:
+
+- Velocity snapshot `01KQ84D3AF9YW6FQCM9SVSM5EG`
+- post-snapshot DB backup
+  `db-backup/openrig-post-velocity-snapshot-20260427T185003Z.sqlite`
+- backup integrity `ok`
+- old daemon PID `62828`, Node 25 global npm install
+- new daemon PID `39708`, Node 22 source runtime
+- post-cutover `example-seat`: 4/4 seats `running` / `ready`
+- `rig restore-check --rig example-seat`: `RESTORABLE WITH CAVEATS`,
+  `20 green | 9 yellow | 0 red`, `RECOVERY: NOT NEEDED`
+
+Important caveat: this proves hot daemon cutover for tmux-backed Claude seats on
+this host and commit range. It does not prove that arbitrary migrations,
+non-tmux runtimes, service-backed rigs, or dead sessions can be recovered without
+separate testing.
+
+## 2026-05-02 Proof Point
+
+Continuity targets:
+
+- `kernel`
+- `openrig-discovery`
+- `openrig-dogfood`
+- `openrig-lifecycle`
+- `openrig-maintenance`
+- `openrig-product-lab`
+- `example-rig`
+- `example-seat`
+
+Pinned daemon:
+
+- commit `6af2754824a07291562622ac019b68615fc41abe`
+- runtime worktree `~/code/projects/openrig-runtime-6af2754`
+- wrapper `~/.openrig/bin/rig-real-6af2754`
+
+Pattern proven:
+
+- lifecycle/runtime-upgrade prepared the decision and preflight artifacts;
+- a host-local tmux sidecar (`host-upgrade-operator-6af2754`) was spawned
+  outside the managed topology with the current operator context;
+- the sidecar stopped only the daemon, using verified PID fallback after
+  `rig daemon stop` refused due to missing daemon state;
+- the sidecar started the target daemon on port `7433`, repointed the
+  config-layer wrapper default, verified protected topology, ran targeted
+  Agent Starter smoke/tests, wrote evidence, and unblocked Dogfood;
+- Velocity delivery continued working throughout the cutover.
+
+Evidence:
+
+- preflight:
+  (internal upgrade-preflight evidence, 2026-05-01)
+- live cutover:
+  (internal live-cutover evidence, 2026-05-02)
+
+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
+
+Detailed field note:
+
+(internal upgrade-brittleness field note, 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` is too noisy on this host. 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.
+
+Separate follow-on note, not part of the daemon-upgrade SOP:
+
+(internal add-node-brittleness field note, 2026-04-27)
+
+## 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.
+
+```bash
+rig snapshot <rigId>
+rig down <rigId>
+# upgrade daemon/CLI
+rig up <rigName>
+rig restore-check --rig <rigName>
+```
+
+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
+
+Do not proceed with hot upgrade if:
+
+- 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.
+
+## 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.
+
+For npm runtime:
+
+```bash
+npm install -g @openrig/cli@<previous-version>
+rig daemon stop
+rig daemon start
+```
+
+## 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:
+  rigx/default `rig` 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.**