test: prove R11 control-plane replacement safety

Author: myobie

INVARIANTS.md

@@ -5,7 +5,7 @@ materialization, messaging, DING, or presence must preserve them.
 
 | Invariant | Guarantee | Proof |
 |---|---|---|
-| **Supervisor-decoupled lifecycle** | SIGTERM or SIGKILL of st2 never kills a task. A new runner adopts survivors; only explicit teardown kills. This covers PTY and exec tasks. | `tests/nomad_survival.rs` |
+| **R11 control-plane replacement safety** | Normal stop or SIGKILL of `st2 up`, atomic binary replacement, and control-plane restart leave live PTY and exec agents usable with the same PID and creation identity. The replacement adopts each survivor exactly once, launches only genuinely missing work, and never duplicates a survivor; only explicit teardown kills an agent. | `tests/nomad_survival.rs::normal_stop_and_binary_replacement_adopt_exec_unchanged_without_duplicate`; `tests/nomad_survival.rs::forced_kill_and_binary_replacement_adopt_exec_unchanged_without_duplicate`; `tests/nomad_survival.rs::normal_stop_and_binary_replacement_adopt_pty_unchanged_without_duplicate`; `tests/nomad_survival.rs::forced_kill_and_binary_replacement_adopt_pty_unchanged_without_duplicate`; `tests/nomad_survival.rs::explicit_teardown_kills_exec_but_plain_stop_does_not`; `tests/nomad_survival.rs::explicit_teardown_kills_pty_but_plain_stop_does_not` |
 | **Transport-decoupled lifecycle** | Each task is isolated from a supervisor/transport process-group or cgroup cascade. | `tests/transport_isolation.rs`; `tests/transport_isolation_macos.rs` |
 | **Clean exec teardown** | Killing an exec task reaps its whole process group. | `tests/exec_backend.rs::exec_kill_reaps_the_whole_process_group_not_just_the_leader` |
 | **Bounded restart diagnostics** | Relaunching an exec task preserves the just-finished log as one prior generation while bounding retained diagnostics to current plus prior. Final retirement removes the PID and both logs. | `tests/exec_backend.rs::exec_restart_reap_keeps_bounded_diagnostics_and_final_remove_cleans_them`; `tests/run.rs::up_once_finally_removes_dead_retired_tasks_without_restarting_them` |

README.md

@@ -172,6 +172,30 @@ For a foreground supervisor on any host:
 st2 up --catalog "$CATALOG" --host <host>
 ```
 
+### Staged control-plane replacement gate
+
+`st2 up` is a replaceable control plane, not the lifetime owner of an agent. Stopping it normally
+or killing it must leave every agent running. `st2 down` and declaration retirement are separate,
+explicit lifecycle actions and must never be used merely to replace the control plane.
+
+Every staged recovery or binary cutover must retain a pre-stop receipt of each agent's stable task
+identity, PID, and process-creation identity. Install the verified replacement binary atomically
+while those tasks continue running, restart the control plane, and do not accept the host until its
+first reconcile proves all of the following:
+
+- every pre-existing agent is still usable with the same PID and creation identity;
+- the replacement reports those agents as adopted and does not launch or duplicate them;
+- only genuinely missing declared work is launched;
+- explicit teardown remains the only path that stops an agent.
+
+The executable gate drives the real st2 binary and both PTY and exec backends through normal stop,
+forced kill, atomic binary replacement, adoption, a live-task heartbeat, and a duplicate-boot
+receipt:
+
+```sh
+cargo test --test nomad_survival --all-features
+```
+
 ## Messages, DING, status, and context
 
 Inside a managed task, `CATALOG`, `ST_ROOT`, and `ST_AGENT` are already set:

docs/vrs/requirements.md

@@ -56,6 +56,12 @@ accepted.
   launch fields.
 - **R07 Verified hooks:** Required hook content is installed explicitly and
   verified before a rendered agent depends on it.
+- **R11 Control-plane replacement safety:** Stopping or killing `st2 up` must
+  not stop, restart, or replace any agent it launched. st2 can be reinstalled
+  and restarted while running agents continue unchanged; the replacement
+  control plane adopts those existing processes by stable identity and starts
+  only genuinely missing work. Stopping an agent is a separate, explicit
+  lifecycle action.
 
 ### Must externalize agent state and scope
 

docs/vrs/spec.md

@@ -11,8 +11,9 @@ replacement for the README, CLI help, KDL examples, or tests.
 ## Scope
 
 st2 validates a declared agent fleet, materializes agent workspaces, launches
-host-local work, supervises restartable tasks, and delivers messages. The
-agent grammar and harness-facing contract remain canonical in
+host-local work, adopts and supervises independently surviving tasks, and
+delivers messages. The agent grammar and harness-facing contract remain
+canonical in
 [`compoundingtech/evals/AGENT-SPEC.md`](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md).
 
 ## Host-local scheduling and supervision
@@ -46,6 +47,17 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
   launcher so manual and supervised restarts are equivalent.
 - **R07:** Hook bundles are explicit, content-addressed, installed separately,
   and verified before materialization references them.
+- **R11:** `st2 up` is a replaceable control plane, not the lifetime owner of
+  its agents. Normal exit, forced termination, binary replacement, and restart
+  leave every running agent PID and creation identity unchanged. The new
+  control plane adopts those processes and starts only missing work; it does
+  not duplicate them. Agent stop or retirement requires a separate explicit
+  lifecycle action.
+
+  Executable acceptance starts an agent, terminates `st2 up` normally and with
+  a forced kill, verifies the agent remains alive and usable, replaces the st2
+  binary, starts the control plane again, and proves adoption with the same
+  agent PID/creation identity and no duplicate process.
 
 ## Message lifecycle
 

docs/vrs/vision.md

@@ -36,6 +36,9 @@
    path, with unsupported behavior stated plainly.
 2. A canonical agent declaration can be validated, materialized, launched, and
    restarted without losing its effective launch definition or durable state.
+   The st2 control plane itself can be stopped, killed, reinstalled, and
+   restarted without stopping or replacing any running agent; the replacement
+   runtime adopts the existing agent processes without duplication.
 3. Every machine has exactly one root agent that observes local health,
    resolves bounded runtime failures, and escalates what it cannot resolve.
 4. A human, CoS, root, or supervisor can inspect catalog-backed state to