fix: early health responder on pre-bound socket — Wave 54

Health check unresponsive on southGate NUCLEUS: pre-bound socket
accepted connections but accept loop didn't start until full handler
was ready (~4-8s gap). Added spawn_early_health_responder() that
responds to health.liveness/health.check/health.readiness immediately
while executor initializes. BTSP not required for health probes.
3 new tests, 9,161+ lib tests, 0 clippy.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: BiomeOS Developer

CHANGELOG.md

@@ -5,7 +5,17 @@ All notable changes to ToadStool will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - May 26, 2026 (Sessions 43-276)
+## [Unreleased] - May 27, 2026 (Sessions 43-277)
+
+### Session S277 (May 27, 2026) — Wave 54: Early Health Responder
+
+primalSpring Wave 54 response: health check unresponsive on southGate fixed.
+
+- FIXED: Health probes unresponsive during startup — pre-bound socket accepted connections but nobody called accept() until full handler was ready (~4-8s gap)
+- ADDED: `spawn_early_health_responder()` — accepts connections on pre-bound socket immediately, responds to `health.liveness`/`health.check`/`health.readiness` while executor initializes
+- CHANGED: `serve_unix_prebound()` now takes `Arc<UnixListener>` — shared between early responder and full handler
+- DOCUMENTED: BTSP is NOT required for health probes (plaintext auto-detection), socket naming (TOADSTOOL_SOCKET env var override)
+- METRICS: 9,161+ lib tests, 0 clippy warnings
 
 ### Session S276 (May 26, 2026) — Deep Debt Evolution II
 

DEBT.md

@@ -1,13 +1,21 @@
 # Active Technical Debt Register
 
-**Date**: May 2026 — S276
+**Date**: May 2026 — S277
 **Philosophy**: Math is universal, precision is silicon. Workarounds are
 short-term solutions that increase debt. We aim to solve deep debt over
 iterations, evolving toward vendor-agnostic, capability-based solutions—
 with production stubs surfacing typed configuration errors and capability
 guidance, and auth policy driven by explicit environment configuration
 where applicable.
 
+**S277 (Wave 54: Early Health Responder)**:
+Health check unresponsive on southGate NUCLEUS — pre-bound socket accepted
+connections but accept loop didn't start until full handler was ready (~4-8s).
+Added `spawn_early_health_responder()` that responds to health.liveness/
+health.check/health.readiness immediately on the pre-bound socket while
+executor initializes. BTSP NOT required for health probes (plaintext
+auto-detection). 9,161+ lib tests, 0 clippy.
+
 **S275 (Wave 49: Ecosystem Tightening)**:
 Showcase fossilized (35 files → `fossilRecord/primals/toadStool/showcase_wave49/`).
 36 wateringHole handoffs mirrored to central (8 active, 28 archived). Stale

DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # ToadStool Documentation Hub
 
-**Last Updated**: May 2026 — S276
+**Last Updated**: May 2026 — S277
 
 ---
 
@@ -30,11 +30,11 @@ These root documents were **fully resolved** and **fossilized** in wateringHole
 
 ---
 
-## Current State (S276 — May 2026)
+## Current State (S277 — May 2026)
 
 **Post-budding, dependency-sovereign, IPC-first, fully concurrent, capability-based.** barraCuda is a separate primal at `ecoPrimals/barraCuda/`. ToadStool is the hardware infrastructure layer — GPU/NPU/CPU discovery, capability probing, workload orchestration, and shader dispatch.
 
-- **23,000+ tests** (9,158+ lib-only), 0 failures, 0 clippy warnings, 0 fmt diffs. Full workspace concurrent test suite.
+- **23,000+ tests** (9,161+ lib-only), 0 failures, 0 clippy warnings, 0 fmt diffs. Full workspace concurrent test suite.
 - **88 JSON-RPC methods** (direct) + semantic registry. Wire Standard L3 (partial): `cost_estimates`, `operation_dependencies`. **Recommended caller timeout: ≥3 seconds** for health probes during startup.
 - **Phase C complete** (S245–S253) — toadstool-cylinder (153 .rs, 700 tests), DRM/MMIO/AMD/NVIDIA/VFIO hardware modules absorbed from `coral-driver`. `OwnedFd` VFIO fd ownership (S253). SwapOrchestrator real quiesce/persist/restore (S253). `toadstool device` CLI with swap/list/status/warm subcommands (S253). GspBridge trait boundary.
 - **Phase D: Sovereign dispatch validated** (S250–S263) — `try_local_dispatch()` via `ComputeDevice` trait before `coral_client` IPC forward. Full buffer lifecycle. AMD DRM dispatch live. **NV VFIO e2e dispatch validated on Titan V** (S263): warm handoff → VFIO open → channel → DMA roundtrip → GR init. Current frontier: FECS PENDING_CTX_RELOAD.
@@ -44,13 +44,14 @@ These root documents were **fully resolved** and **fossilized** in wateringHole
 - **Sandbox working_dir production** (S269) — `data_dependencies` pre-dispatch validation with BLAKE3 integrity. `SandboxSpec.working_directory` wired into sandbox manager. 90+ upstream clippy errors absorbed.
 - **Deep Debt** (S240–S273) — All Duration literals extracted to named constants. `CORALREEF_*` env vars deprecated with `TOADSTOOL_*` primaries + deprecation warnings (S253). Zero `#[allow(deprecated)]` remaining. All lint attrs have `reason`. Zero production mocks/TODO/FIXME/unreachable!(). All unsafe SAFETY-documented. `cargo deny check bans` passes clean.
 - **Deep Debt Evolution** (S273) — Production panic surface eliminated (`kernel_health.rs`, dispatch cache, `ember_client.rs`, `secure_enclave`). `dispatch/mod.rs` 1,638→839L via `dispatch/sovereign.rs` extraction. `warm_init.rs` → module dir. 6 CLI `well_known::*` sites migrated to capability-based discovery. VFIO `activity_tracker().record()` wired. hw-safe abstractions validated.
+- **Wave 54: Early Health Responder** (S277) — Health check unresponsive on southGate fixed. Early health responder on pre-bound socket during startup. BTSP not required for health probes.
 - **Deep Debt Evolution II** (S276) — Remaining production unwrap/expect/unreachable eliminated. `handler/sovereign.rs` 1,003L → module directory. `memmap2` removed from hw-safe (rustix mmap). 3 primal-name type aliases deprecated. `ipc.register` capability list aligned to Node Atomic set.
 - **Capability-based everywhere**: 6 CLI hardcoded primal name sites migrated to capability-based discovery (S273); ~400 intentional legacy-compat refs remain (env fallbacks, serde aliases). 0 production mocks. All production logging via `tracing`.
 - **ecoBin v3.0** — Zero C FFI deps. `deny.toml` ring + async-trait + zstd-sys bans active.
 - **46 unsafe blocks** (all in hw-safe/GPU/VFIO/display/plugin containment crates); all SAFETY-documented. Workspace `unsafe_code = "deny"`, **41 crates `forbid`**.
 - **Dual-socket IPC** — `compute.sock` (JSON-RPC primary) + `compute-tarpc.sock` (tarpc hot-path).
 
-See [CHANGELOG.md](CHANGELOG.md) for full session-by-session history (S43–S276).
+See [CHANGELOG.md](CHANGELOG.md) for full session-by-session history (S43–S277).
 
 ---
 

NEXT_STEPS.md

@@ -1,9 +1,9 @@
 # ToadStool -- Next Steps
 
-**Updated**: May 2026 — S276 (Deep Debt Evolution II: unwrap elimination, sovereign split, memmap2 removal. 88+ JSON-RPC methods. 9,158+ lib tests.)
-**Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | tests verified (23,000+ workspace, 0 failures; 9,158+ lib-only) | **88+ JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | **Zero production panics/expects** | **Zero production TODO/FIXME/HACK** | **Zero production unreachable!()** | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **46 unsafe blocks** (all in hw containment, all SAFETY-documented) | **rustix 1.x workspace-wide** | **capability-based primal references (no hardcoded names)** | **`async-trait` DEPRECATED** (banned in `deny.toml`) | **`deny.toml` ring + async-trait + zstd-sys bans active** | **Zero external mmap deps (memmap2 removed S276)** | **Phase D dispatch live** | **E2E sovereign dispatch VALIDATED on Titan V (warm handoff)**
-**Latest**: S276 — **Deep Debt Evolution II**: Production unwrap/expect/unreachable eliminated. `handler/sovereign.rs` 1,003L → module directory. `memmap2` removed from hw-safe (rustix mmap). 3 primal-name aliases deprecated. `ipc.register` capabilities aligned to Node Atomic. 9,158+ lib tests.
-**Previous**: S275 — Wave 49 Ecosystem Tightening. S274 — Glacial Horizon: max_guest_load wired. S273 — Deep Debt Evolution. S268 — Kernel Health Preflight. S267 — Sovereign driver rotation.
+**Updated**: May 2026 — S277 (Wave 54: Early Health Responder. 88+ JSON-RPC methods. 9,161+ lib tests.)
+**Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | tests verified (23,000+ workspace, 0 failures; 9,161+ lib-only) | **88+ JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | **Zero production panics/expects** | **Zero production TODO/FIXME/HACK** | **Zero production unreachable!()** | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **46 unsafe blocks** (all in hw containment, all SAFETY-documented) | **rustix 1.x workspace-wide** | **capability-based primal references (no hardcoded names)** | **`async-trait` DEPRECATED** (banned in `deny.toml`) | **`deny.toml` ring + async-trait + zstd-sys bans active** | **Zero external mmap deps (memmap2 removed S276)** | **Phase D dispatch live** | **E2E sovereign dispatch VALIDATED on Titan V (warm handoff)**
+**Latest**: S277 — **Wave 54: Early Health Responder**: Health check unresponsive on southGate NUCLEUS fixed. Early health responder responds to health.liveness/health.check immediately on pre-bound socket while executor initializes. BTSP not required for health probes. 9,161+ lib tests.
+**Previous**: S276 — Deep Debt Evolution II. S275 — Wave 49 Ecosystem Tightening. S274 — Glacial Horizon: max_guest_load wired. S273 — Deep Debt Evolution. S268 — Kernel Health Preflight.
 
 ---
 

README.md

@@ -1,6 +1,6 @@
 # ToadStool
 
-**Sovereign Compute Hardware** | Pure Rust | ecoBin | May 2026 | S276 | v0.2.0
+**Sovereign Compute Hardware** | Pure Rust | ecoBin | May 2026 | S277 | v0.2.0
 
 ---
 

crates/server/src/pure_jsonrpc/connection/mod.rs

@@ -10,7 +10,7 @@ mod tests;
 mod unix;
 
 pub use tcp::serve_tcp;
-pub use unix::{prebind_unix_listener, serve_unix, serve_unix_prebound};
+pub use unix::{prebind_unix_listener, serve_unix, serve_unix_prebound, spawn_early_health_responder};
 
 use crate::errors::{ServerError, ServerResult};
 use crate::pure_jsonrpc::types::JsonRpcError;

crates/server/src/pure_jsonrpc/connection/tests.rs

@@ -598,3 +598,85 @@ fn test_tcp_idle_timeout_env_override() {
         assert_eq!(timeout, std::time::Duration::from_secs(42));
     });
 }
+
+// ═══════════════════════════════════════════════════════════
+// Early health responder (Wave 54)
+// ═══════════════════════════════════════════════════════════
+
+#[tokio::test]
+async fn early_health_liveness_responds_alive() {
+    let dir = tempfile::tempdir().unwrap();
+    let sock = dir.path().join("test-early-health.sock");
+    let listener = Arc::new(tokio::net::UnixListener::bind(&sock).unwrap());
+    let (stop_tx, stop_rx) = tokio::sync::watch::channel(false);
+
+    let handle = super::spawn_early_health_responder(&listener, stop_rx);
+
+    let mut stream = UnixStream::connect(&sock).await.unwrap();
+    stream
+        .write_all(b"{\"jsonrpc\":\"2.0\",\"method\":\"health.liveness\",\"id\":1}\n")
+        .await
+        .unwrap();
+    stream.flush().await.unwrap();
+
+    let mut buf = vec![0u8; 4096];
+    let n = stream.read(&mut buf).await.unwrap();
+    let resp: serde_json::Value = serde_json::from_slice(&buf[..n]).unwrap();
+    assert_eq!(resp["result"]["status"], "alive");
+    assert_eq!(resp["id"], 1);
+
+    let _ = stop_tx.send(true);
+    handle.await.unwrap();
+}
+
+#[tokio::test]
+async fn early_health_check_responds_starting() {
+    let dir = tempfile::tempdir().unwrap();
+    let sock = dir.path().join("test-early-check.sock");
+    let listener = Arc::new(tokio::net::UnixListener::bind(&sock).unwrap());
+    let (stop_tx, stop_rx) = tokio::sync::watch::channel(false);
+
+    let handle = super::spawn_early_health_responder(&listener, stop_rx);
+
+    let mut stream = UnixStream::connect(&sock).await.unwrap();
+    stream
+        .write_all(b"{\"jsonrpc\":\"2.0\",\"method\":\"health.check\",\"id\":42}\n")
+        .await
+        .unwrap();
+    stream.flush().await.unwrap();
+
+    let mut buf = vec![0u8; 4096];
+    let n = stream.read(&mut buf).await.unwrap();
+    let resp: serde_json::Value = serde_json::from_slice(&buf[..n]).unwrap();
+    assert_eq!(resp["result"]["status"], "starting");
+    assert_eq!(resp["id"], 42);
+
+    let _ = stop_tx.send(true);
+    handle.await.unwrap();
+}
+
+#[tokio::test]
+async fn early_health_unknown_method_returns_error() {
+    let dir = tempfile::tempdir().unwrap();
+    let sock = dir.path().join("test-early-unknown.sock");
+    let listener = Arc::new(tokio::net::UnixListener::bind(&sock).unwrap());
+    let (stop_tx, stop_rx) = tokio::sync::watch::channel(false);
+
+    let handle = super::spawn_early_health_responder(&listener, stop_rx);
+
+    let mut stream = UnixStream::connect(&sock).await.unwrap();
+    stream
+        .write_all(b"{\"jsonrpc\":\"2.0\",\"method\":\"compute.submit\",\"id\":99}\n")
+        .await
+        .unwrap();
+    stream.flush().await.unwrap();
+
+    let mut buf = vec![0u8; 4096];
+    let n = stream.read(&mut buf).await.unwrap();
+    let resp: serde_json::Value = serde_json::from_slice(&buf[..n]).unwrap();
+    assert_eq!(resp["error"]["code"], -32002);
+    assert!(resp["error"]["message"].as_str().unwrap().contains("initializing"));
+
+    let _ = stop_tx.send(true);
+    handle.await.unwrap();
+}

crates/server/src/pure_jsonrpc/connection/unix.rs

@@ -33,7 +33,7 @@ use super::process_request;
 ///
 /// Returns [`ServerError`] if directory creation, socket bind, or permission setting fails.
 pub async fn serve_unix(handler: Arc<JsonRpcHandler>, socket_path: PathBuf) -> ServerResult<()> {
-    let listener = prebind_unix_listener(&socket_path).await?;
+    let listener = Arc::new(prebind_unix_listener(&socket_path).await?);
     serve_unix_prebound(handler, listener).await
 }
 
@@ -93,13 +93,87 @@ pub async fn prebind_unix_listener(socket_path: &std::path::Path) -> ServerResul
     Ok(listener)
 }
 
+/// Spawn a minimal health-only accept loop on a pre-bound listener.
+///
+/// Accepts connections and responds to `health.liveness` / `health.check` /
+/// `health.readiness` with immediate JSON-RPC responses while the full
+/// `JsonRpcHandler` is still being constructed. All other methods return
+/// a `-32002` "server initializing" error.
+///
+/// Returns a `JoinHandle` that resolves when `stop` receives a value. The
+/// caller should send to `stop` once the full handler is ready, then
+/// pass the same `listener` to [`serve_unix_prebound`].
+pub fn spawn_early_health_responder(
+    listener: &Arc<UnixListener>,
+    mut stop: tokio::sync::watch::Receiver<bool>,
+) -> tokio::task::JoinHandle<()> {
+    let listener = Arc::clone(listener);
+    tokio::spawn(async move {
+        loop {
+            tokio::select! {
+                biased;
+                _ = stop.changed() => break,
+                result = listener.accept() => {
+                    match result {
+                        Ok((stream, _)) => {
+                            tokio::spawn(handle_early_health(stream));
+                        }
+                        Err(e) => {
+                            warn!("Early health accept error: {e}");
+                        }
+                    }
+                }
+            }
+        }
+        info!("Early health responder stopped — full handler taking over");
+    })
+}
+
+async fn handle_early_health(stream: UnixStream) {
+    let (reader, mut writer) = stream.into_split();
+    let mut reader = BufReader::new(reader);
+    let mut line = String::new();
+    if reader.read_line(&mut line).await.is_err() || line.trim().is_empty() {
+        return;
+    }
+    let trimmed = line.trim();
+
+    let method = serde_json::from_str::<serde_json::Value>(trimmed)
+        .ok()
+        .and_then(|v| v.get("method")?.as_str().map(String::from));
+    let id = serde_json::from_str::<serde_json::Value>(trimmed)
+        .ok()
+        .and_then(|v| v.get("id").cloned())
+        .unwrap_or(serde_json::Value::Null);
+
+    let response = match method.as_deref() {
+        Some("health.liveness") => {
+            serde_json::json!({"jsonrpc":"2.0","result":{"status":"alive"},"id":id})
+        }
+        Some("health.check" | "toadstool.health" | "compute.health") => {
+            serde_json::json!({"jsonrpc":"2.0","result":{"status":"starting","uptime_secs":0},"id":id})
+        }
+        Some("health.readiness") => {
+            serde_json::json!({"jsonrpc":"2.0","result":{"status":"starting"},"id":id})
+        }
+        _ => {
+            serde_json::json!({"jsonrpc":"2.0","error":{"code":-32002,"message":"Server initializing"},"id":id})
+        }
+    };
+
+    let mut buf = serde_json::to_vec(&response).unwrap_or_default();
+    buf.push(b'\n');
+    let _ = writer.write_all(&buf).await;
+    let _ = writer.flush().await;
+}
+
 /// Serve JSON-RPC on a pre-bound Unix socket listener.
 ///
 /// Used with [`prebind_unix_listener`] to start accepting connections
 /// on a listener that was bound before the full handler was constructed.
 pub async fn serve_unix_prebound(
     handler: Arc<JsonRpcHandler>,
-    listener: UnixListener,
+    listener: Arc<UnixListener>,
 ) -> ServerResult<()> {
     let env = toadstool_common::primal_sockets::SocketPathEnv::from_env();
     let btsp_required = toadstool_common::primal_sockets::is_btsp_required(&env);

crates/server/src/pure_jsonrpc/mod.rs

@@ -27,7 +27,7 @@ mod connection;
 mod handler;
 mod types;
 
-pub use connection::{prebind_unix_listener, process_request, serve_tcp, serve_unix, serve_unix_prebound};
+pub use connection::{prebind_unix_listener, process_request, serve_tcp, serve_unix, serve_unix_prebound, spawn_early_health_responder};
 pub use handler::HwLearnHandler;
 pub use handler::JsonRpcHandler;
 pub use types::{JsonRpcError, JsonRpcRequest, JsonRpcResponse, JsonWorkloadSubmission};

crates/server/src/unibin/execution.rs

@@ -180,7 +180,7 @@ pub async fn start_servers_with_fallback(
     jsonrpc_socket: PathBuf,
     tcp_port: Option<u16>,
     cfg: &UnibinExecutionConfig,
-    jsonrpc_listener: Option<tokio::net::UnixListener>,
+    jsonrpc_listener: Option<Arc<tokio::net::UnixListener>>,
 ) -> ServerResult<()> {
     if let Some(port) = tcp_port {
         info!("   --port {port} specified: starting TCP JSON-RPC (UniBin standard)");
@@ -216,7 +216,7 @@ async fn try_unix_servers(
     jsonrpc_handler: &Arc<JsonRpcHandler>,
     socket_path: &PathBuf,
     jsonrpc_socket: &PathBuf,
-    jsonrpc_listener: Option<tokio::net::UnixListener>,
+    jsonrpc_listener: Option<Arc<tokio::net::UnixListener>>,
 ) -> ServerResult<()> {
     if let Some(parent) = socket_path.parent() {
         tokio::fs::create_dir_all(parent)