fix(kubernetes): prevent stop-start relay race

[johntmyers]

Summary

Fix a Kubernetes v1beta1 stop/start race that allowed a sandbox to report Stopped and restart while its previous pod was still terminating. The old supervisor could then close the newly claimed exec relay before reporting an exit status.

The regression was exposed by #2884: intentional lifecycle shutdown discards the canonical process exit result, but the new terminal-finalization loop treated that discarded result as unfinalized and retried until Kubernetes exhausted its 30-second termination grace period.

Affected CI evidence

Each linked job failed in sandbox_stop_start_preserves_workspace with exec relay closed before the command reported an exit status:

• PR #3040
• PR #3040 merge queue
• PR #2823
• PR #2643
• PR #3042
• PR #2962

Related Issue

No issue required: this is a localized regression fix with an existing deterministic lifecycle E2E test and CI evidence across unrelated PRs.

Changes

• Acknowledge main-process finalization during intentional Deleting, Stopping, and Stopped lifecycle transitions so the supervisor can terminate promptly.
• Require both Suspended=True and deletion of the old pod before a Kubernetes v1beta1 stop completes.
• Preserve the v1alpha1 fallback, where pod deletion alone is the usable stop-completion signal.
• Add unit coverage for the finalization and stop-completion invariants.
• Document the stronger Kubernetes stop contract in the driver and published compute-driver reference.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• Existing Kubernetes lifecycle E2E regression coverage exercised
• cargo test -p openshell-driver-kubernetes --lib (228 passed)
• OPENSHELL_E2E_KUBE_TEST=sandbox_lifecycle mise run e2e:kubernetes (7 passed, including sandbox_stop_start_preserves_workspace)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (not applicable; driver and published behavior references updated)

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3064.docs.buildwithfern.com/openshell

[github-actions]

Label test:e2e-kubernetes applied for 37962b6. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute Kubernetes HA and credential-driver E2E after building the required gateway and supervisor images once. This is an optional proof-of-life suite; failures are visible in the workflow run but do not publish a required CI gate status.

[github-actions]

Label test:e2e applied for 37962b6. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.