ModelForge-Public/docs/operations/RUNBOOK_NODE_LIFECYCLE.md

Runbook: temporarily enable or disable a compute node

Use the lifecycle action for planned temporary maintenance. Permanent removal belongs in RUNBOOK_NODE_DECOMMISSION.md; credential loss belongs in RUNBOOK_NODE_LOSS.md.

Disable

1. Drain and stop workloads before starting. The Console's admin-only Review disable impact preview checks active deployments, requests, jobs, runtime probes, leases, residencies, pending transitions, storage dependencies and other known node references. A blocker means resolve the dependency and request a fresh preview; there is no force option.
2. Confirm the preview names the intended persisted node identity. Enter the operator identity, a reason of at least ten characters, and that persisted identity exactly.
3. The API rechecks the dependency digest while holding the node and dependency locks, then advances the node generation with compare-and-swap. A 409 means the review is stale or a dependency still exists; inspect the new state and review again.
4. Disabled nodes reject agent heartbeats and cannot claim new agent work. Do not treat the action as a graceful drain; the preview refuses known active workloads instead.

Enable

1. Resolve a lost/revoked credential first using RUNBOOK_NODE_LOSS.md. Remote nodes without an active node credential cannot be enabled.
2. Use Review enable impact, inspect the current state and type the persisted identity with the operator identity and reason.
3. A successful enable leaves the remote node offline and clears old heartbeat/protocol/capability facts. The agent must authenticate and send a fresh compatible heartbeat before health or scheduler readiness can be inferred. The action does not start or restart the agent on its host.

Never change enabled through the metadata PATCH; the API rejects that field. Use the preview and execute lifecycle endpoints so impact, generation and audit checks cannot be skipped. Do not rehearse on production nodes.