docs(runbooks): validator BYO-secrets migration runbook

[bdchatham]

Adds .agent/runbooks/migrating-validator-to-byo-secrets.md (+ index row) — the cutover procedure for moving a live validator off a legacy EC2 host onto the platform, carrying its consensus identity via SOPS-encrypted Secrets. Written from the arctic-1 node-19 harbor dry-run.

Contents

• What migrates — priv_validator_key.json (the identity) + node_key.json; chain state does not.
• SOPS extract/encrypt — against the real platform per-cluster .sops.yaml layout (KMS by cluster dir; clusters/prod → alias/prod).
• SND spec + the controller validation surface (validate-signing-key / validate-node-key; operatorKeyring optional post-fix(planner): guard validation gates in buildRunningPlan #380).
• Double-sign safety (the core) — stop-before-start discipline, the replicas:1 CEL guard, the systemctl disable auto-restart seam, and the ValidatorDoubleSignEvidenceObserved / ValidatorNewlyJailed alerts.
• Cutover + rollback sequence, dry-run findings (write-mode↔image, networking.tcp DNS race, deploy-clean-not-recreate, deletionPolicy→PVC cascade, fix(planner): guard validation gates in buildRunningPlan #380 operatorKeyring guard), and a pre-flight checklist.

Review

Cross-reviewed by the platform-engineer and kubernetes-specialist. kubernetes-specialist signed off (wording fixes applied: no block-sync task — corrected to the real bootstrap progression + seid catch-up; mark-ready lives in the SeiNode plan, not the SND's; BYO nodeKey NodeID is Secret-pinned; PVC ownership topology). platform-engineer's two blockers handled:

• SOPS layout — corrected: platform has no root .sops.yaml; secrets live under the cluster dir as *.secret.yaml, encrypted via the cluster's .sops.yaml. Fixed.
• sei-infra removal — re-verified against sei-infra#1034: node-19 is the tail of its eu-central-1 region (nodeStartId 10), removed by that region's instanceCount 10→9 with the nodeStartId 0/10/20 pins preventing the later region from reindexing. The original "decrement kills node-29 / needs state surgery" concern came from reading the raw count module without the inventory/terraform.py region layer; documented the actual (clean) mechanism.

Plus: ValidatorNewlyJailed is for:5m w/ 30m lookback; KMS-by-cluster (dev is us-east-2); downtime-jail vs tombstone caveat; image-gate is a human tag check.

[cursor]

PR Summary

Low Risk
Documentation-only under .agent/runbooks/; no runtime, auth, or deployment code changes.

Overview
Adds .agent/runbooks/migrating-validator-to-byo-secrets.md and an index row in .agent/runbooks/README.md so agents and operators can discover a full cutover guide for moving a live validator from legacy EC2 onto K8s using SOPS-encrypted signingKey / nodeKey Secrets (arctic-1 node-19 pattern).

The new runbook documents what consensus material actually moves, per-cluster SOPS/KMS layout, SeiNodeDeployment shape and controller validation tasks, and stop-before-start double-sign discipline (including systemctl disable, replicas: 1 CEL, and observability alerts). It also spells out ordered cutover/rollback, success criteria, sei-infra tail-node removal via regional instanceCount, harbor dry-run gotchas (write-mode vs image, networking.tcp DNS race, PVC cascade on SeiNode delete, controller ≥ 5d03f33), and a pre-flight checklist.

^{Reviewed by Cursor Bugbot for commit f1fa8f0. Bugbot is set up for automated code reviews on this repo. Configure here.}