refactor(compute): define driver shutdown and restart lifecycle contract

[elezar]

Problem Statement

The OpenShell Drivers roadmap (#1051) requires in-tree and out-of-tree compute drivers to interact with the gateway through the same gRPC contract, but driver shutdown and restart semantics are not defined by compute_driver.proto.

The gateway currently has different lifecycle ownership for in-process drivers, the gateway-managed VM driver process, and operator-managed external driver endpoints. Without a shared contract, graceful gateway shutdown, driver restart, sandbox recovery, and reconnection behavior remain driver-specific and cannot be covered consistently by conformance tests.

Proposed Design

Define a common driver lifecycle contract before adding implementation-specific hooks. The design should specify:

• which component owns starting, stopping, and restarting each driver process;
• whether the protocol needs an explicit graceful-shutdown RPC, a drain or quiesce operation, capability negotiation, or a combination;
• what a successful shutdown response guarantees for running sandboxes and watch streams;
• how the gateway detects driver loss and reconnects after a driver restart;
• how persisted sandboxes are reconciled after gateway or driver restart;
• how unmanaged out-of-tree drivers express unsupported lifecycle operations;
• timeout, idempotency, and error semantics; and
• which behaviors belong in the driver conformance suite (spike: driver conformance suite for compute drivers #2183).

Keep process supervision separate from the protocol. Package managers or operators may own an external process even when the gateway uses a common lifecycle RPC.

Alternatives Considered

• Continue relying on process termination and reconnect behavior only. This leaves graceful drain and recovery semantics implicit and driver-specific.
• Make the gateway supervise every driver process. This does not fit operator-managed out-of-tree endpoints.
• Add a shutdown RPC without first defining its guarantees. This risks encoding incompatible behavior across drivers.

Agent Investigation

• The roadmap lists "Shutdown and restart mechanics" as remaining work but links no issue or PR.
• Repository searches for driver shutdown and restart lifecycle work found no dedicated contract tracker.
• Spike: should the built-in compute drivers move to the external (out-of-process) model? #2061 investigates whether built-in drivers should move out of process, but deliberately does not define the lifecycle protocol.
• Sandboxes stuck in Error after Podman machine restart — no recovery path #2179 and PR fix(compute): recover Error-phase sandboxes on gateway startup #2269 cover a concrete Podman/Docker restart-recovery failure and should inform the common contract.
• spike: driver conformance suite for compute drivers #2183 defines the driver conformance direction and should consume the lifecycle contract once agreed.
• refactor(compute): define a uniform gateway callback endpoint contract #2215 provides a pattern for defining a cross-driver semantic contract before selecting a protobuf shape.

Definition of Done

• Document lifecycle ownership for in-process, gateway-managed, and operator-managed drivers.
• Decide whether new protocol methods or capabilities are required.
• Define shutdown, disconnect, restart, reconnect, and reconciliation semantics.
• Identify migration work for all in-tree drivers and external drivers.
• Add or update implementation issues and conformance scenarios.
• Update the relevant architecture documentation.