feat(supervisor): report experimental bootstrap health over TCP

experimental-bootstrap now takes --health-port instead of a Unix health
socket. It binds the dedicated supervisor's wildcard readiness listener,
reachable at the Pod IP, and accepts and closes connections while the
process runs. The chart probes the named container port health (5502)
with native kubelet tcpSocket checks and drops the health-only emptyDir.
No filesystem state remains to clean up after an unclean exit.

Dedicated supervisors keep --health-socket-path and health --socket.

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

.agents/skills/helm-dev-environment/SKILL.md

@@ -71,8 +71,8 @@ gatewayConfig:
 The gateway chart creates a separate, single-replica idle supervisor Deployment
 in the release namespace, regardless of shared/managed/operator workspace mode.
 Use a supervisor image built from this branch: the bootstrap subcommand is new.
-Check its rollout and exec health probes separately; no sandbox sessions route
-through it. `workspace` is reserved and rejected. Omit the field to disable it.
+Check its rollout and TCP health probes (container port `health`, 5502)
+separately; no sandbox sessions route through it. `workspace` is reserved and rejected. Omit the field to disable it.
 
 ### 2. Deploy OpenShell
 

crates/openshell-supervisor/README.md

@@ -63,8 +63,9 @@ backend or enable a Windows workload runtime.
 
 ## Experimental deployment bootstrap
 
-`openshell-supervisor experimental-bootstrap --health-socket /run/openshell/health.sock`
-starts an idle process for the Kubernetes gateway topology experiment. The private
-Unix socket supports the existing `health --socket` command. No sandbox session
-listener, gateway authentication, or tenant routing is started. SIGTERM and SIGINT
-close the listener and remove the socket. This subcommand is Unix-only.
+`openshell-supervisor experimental-bootstrap --health-port 5502` starts an idle
+process for the Kubernetes gateway topology experiment. The wildcard TCP health
+port accepts and closes connections for kubelet `tcpSocket` probes and reports
+process health only; it keeps no filesystem state. No sandbox session listener,
+gateway authentication, or tenant routing is started. SIGTERM and SIGINT close
+the listener. This subcommand is Unix-only.

crates/openshell-supervisor/src/experimental.rs

@@ -7,15 +7,15 @@ use clap::Parser;
 #[cfg(unix)]
 use miette::IntoDiagnostic;
 use miette::Result;
-use std::path::PathBuf;
 
 #[derive(Debug, Parser)]
 #[command(name = "openshell-supervisor experimental-bootstrap")]
 #[command(about = "Start an idle experimental supervisor; does not accept sandbox sessions")]
 struct Args {
-    /// Private socket reporting process health, not sandbox readiness.
+    /// TCP port accepting connections while the process runs; reports process
+    /// health, not sandbox readiness.
     #[arg(long)]
-    health_socket: PathBuf,
+    health_port: u16,
 }
 
 pub fn run(raw_args: &[String]) -> Result<()> {
@@ -37,28 +37,24 @@ fn run_platform(args: Args) -> Result<()> {
         let mut interrupt =
             tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())
                 .into_diagnostic()?;
-        // The private emptyDir survives a container restart after an unclean exit.
-        match std::fs::remove_file(&args.health_socket) {
-            Ok(()) => {}
-            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
-            Err(error) => return Err(error).into_diagnostic(),
-        }
-        let listener = tokio::net::UnixListener::bind(&args.health_socket).into_diagnostic()?;
+        let health = openshell_supervisor::bind_readiness_tcp(args.health_port)
+            .and_then(tokio::net::TcpListener::from_std)
+            .into_diagnostic()?;
         eprintln!("Experimental supervisor bootstrap started; sandbox sessions are disabled");
-        let result = loop {
+        loop {
             tokio::select! {
-                result = listener.accept() => {
+                // A connection is the whole check; nothing is exchanged.
+                result = health.accept() => {
                     if let Err(error) = result {
-                        break Err(error).into_diagnostic();
+                        eprintln!("experimental supervisor health accept failed: {error}");
+                        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
                     }
                 }
-                _ = terminate.recv() => break Ok(()),
-                _ = interrupt.recv() => break Ok(()),
+                _ = terminate.recv() => break,
+                _ = interrupt.recv() => break,
             }
-        };
-        drop(listener);
-        std::fs::remove_file(&args.health_socket).into_diagnostic()?;
-        result
+        }
+        Ok(())
     })
 }
 

crates/openshell-supervisor/src/lib.rs

@@ -175,8 +175,9 @@ impl ReadinessEndpoint {
     }
 }
 
-/// Falls back to IPv4 when the network namespace has IPv6 disabled.
-fn bind_readiness_tcp(port: u16) -> std::io::Result<std::net::TcpListener> {
+/// Binds a nonblocking wildcard listener reachable at the Pod IP. Falls back to
+/// IPv4 when the network namespace has IPv6 disabled.
+pub fn bind_readiness_tcp(port: u16) -> std::io::Result<std::net::TcpListener> {
     use socket2::{Domain, Socket, Type};
 
     let bind = |domain: Domain, address: std::net::SocketAddr| {

deploy/helm/openshell/templates/experimental-supervisor.yaml

@@ -52,8 +52,12 @@ spec:
           imagePullPolicy: {{ get (dict "always" "Always" "if_not_present" "IfNotPresent" "never" "Never") (get $kubernetes "supervisor_image_pull_policy" | default "if_not_present") | quote }}
           args:
             - experimental-bootstrap
-            - --health-socket
-            - /run/openshell/health.sock
+            - --health-port
+            - "5502"
+          ports:
+            - name: health
+              containerPort: 5502
+              protocol: TCP
           securityContext:
             allowPrivilegeEscalation: false
             readOnlyRootFilesystem: true
@@ -66,15 +70,9 @@ spec:
             limits:
               memory: 128Mi
           readinessProbe:
-            exec:
-              command: [/openshell-supervisor, health, --socket, /run/openshell/health.sock]
+            tcpSocket:
+              port: health
           livenessProbe:
-            exec:
-              command: [/openshell-supervisor, health, --socket, /run/openshell/health.sock]
-          volumeMounts:
-            - name: health
-              mountPath: /run/openshell
-      volumes:
-        - name: health
-          emptyDir: {}
+            tcpSocket:
+              port: health
 {{- end }}

deploy/helm/openshell/tests/experimental_supervisor_test.yaml

@@ -34,8 +34,28 @@ tests:
           path: spec.template.spec.containers[0].image
           value: example.com/supervisor:experiment
       - equal:
-          path: spec.template.spec.containers[0].args[0]
-          value: experimental-bootstrap
+          path: spec.template.spec.containers[0].args
+          value: [experimental-bootstrap, --health-port, "5502"]
+      - equal:
+          path: spec.template.spec.containers[0].ports
+          value:
+            - name: health
+              containerPort: 5502
+              protocol: TCP
+      - equal:
+          path: spec.template.spec.containers[0].readinessProbe
+          value:
+            tcpSocket:
+              port: health
+      - equal:
+          path: spec.template.spec.containers[0].livenessProbe
+          value:
+            tcpSocket:
+              port: health
+      - notExists:
+          path: spec.template.spec.containers[0].volumeMounts
+      - notExists:
+          path: spec.template.spec.volumes
       - equal:
           path: spec.template.spec.automountServiceAccountToken
           value: false

skills/debug-openshell-cluster/SKILL.md

@@ -55,8 +55,8 @@ When the installed gateway configuration enables
 `[openshell.drivers.kubernetes].experimental_supervisor_topology = "gateway"`,
 Helm creates `<fullname>-experimental-supervisor` in the gateway namespace.
 Inspect that Deployment separately from per-sandbox supervisor Pods. This applies
-to shared, managed, and operator workspace modes. Its probes report idle process
-health, not sandbox session readiness; it does not serve sandboxes yet. Consult
+to shared, managed, and operator workspace modes. Its TCP probes on container
+port `health` (5502) report idle process health, not sandbox session readiness; it does not serve sandboxes yet. Consult
 the published gateway configuration reference for the installed version. Omit
 the setting and upgrade the release to remove the experimental Deployment.