S275: Wave 49 ecosystem tightening — showcase, deploy patterns, startup latency

Showcase fossilized (35 files → fossilRecord/primals/toadStool/showcase_wave49/).
36 wateringHole handoffs mirrored to central (8 active, 28 archived).
Stale deploy patterns fixed: target/release/toadstool → plasmidBin,
cargo install → plasmidBin depot, akida script prefers depot binary.

Startup latency (>8s → ~3s): deferred wgpu GPU enumeration via background
tokio::spawn (saves 1-5s), JSON-RPC socket pre-bound before create_executor
via prebind_unix_listener + serve_unix_prebound (health probes connect
during heavy init). notify-plasmidbin.yml confirmed active.

9,149 lib tests, 0 clippy warnings.

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

Author: BiomeOS Developer

.cargo/config.toml

@@ -8,7 +8,7 @@
 # This enables proper override via [lints.clippy] for transitive dep conflicts
 # genomeBin PIE compliance: verified — x86_64 and aarch64 Linux default to PIE.
 # Explicit flag not needed; would conflict with target-specific rustflags.
-# Verified: `file target/release/toadstool` → "ELF 64-bit LSB pie executable"
+# Verified: PIE output via `file` on plasmidBin-built binary → "ELF 64-bit LSB pie executable"
 
 # ============================================================================
 # DEV LINKER SELECTION (x86_64 Linux native target)

CHANGELOG.md

@@ -5,7 +5,18 @@ 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 24, 2026 (Sessions 43-274)
+## [Unreleased] - May 25, 2026 (Sessions 43-275)
+
+### Session S275 (May 25, 2026) — Wave 49: Ecosystem Tightening
+
+primalSpring Wave 49 response: three cleanup vectors (showcase fossilization, wateringHole consolidation, stale deploy patterns) plus startup latency pipeline debt.
+
+- FOSSILIZED: `showcase/` (35 files, 8 progressive API demos) archived to `fossilRecord/primals/toadStool/showcase_wave49/`, replaced with pointer README
+- MIRRORED: 36 wateringHole handoffs to central `infra/wateringHole/` — 8 active to `handoffs/`, 28 historical to `handoffs/archive/`
+- FIXED: Stale deploy patterns — `target/release/toadstool` in `.cargo/config.toml` and `AKIDA_DRIVER_DEPLOYMENT.md`, `cargo install` in CLI README, akida install script now prefers plasmidBin depot binary
+- OPTIMIZED: Startup latency (>8s cold launch → ~3s) via deferred wgpu GPU enumeration (`tokio::spawn` background discovery, fast baseline returned immediately) and JSON-RPC socket pre-bind (`prebind_unix_listener` + `serve_unix_prebound` — socket bound before `create_executor`, health probes connect during init)
+- VERIFIED: `notify-plasmidbin.yml` active on `main` push, no `which toadstool` patterns
+- METRICS: 88 JSON-RPC methods, 9,149 lib tests, 0 clippy warnings, deny clean
 
 ### Session S274 (May 24, 2026) — Glacial Horizon: Yield-to-Owner Dispatch (Fully Wired)
 

DEBT.md

@@ -1,13 +1,24 @@
 # Active Technical Debt Register
 
-**Date**: May 2026 — S274
+**Date**: May 2026 — S275
 **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.
 
+**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
+deploy patterns fixed: `target/release/toadstool` refs → plasmidBin,
+`cargo install` → plasmidBin depot docs, akida install script prefers depot
+binary. Startup latency (>8s cold launch) reduced via two optimizations:
+deferred wgpu GPU enumeration (1–5s saved — background `tokio::spawn`),
+JSON-RPC socket pre-bind before executor creation (health probes connect
+during init). `prebind_unix_listener` + `serve_unix_prebound` added.
+`notify-plasmidbin.yml` confirmed active. 9,149 lib tests, 0 clippy.
+
 **S274 (Glacial Horizon: Yield-to-Owner Dispatch — FULLY WIRED)**:
 `max_guest_load` yield semantics evolved from types-only (S269) to enforced
 and wired into production dispatch. `check_guest_load()` in

crates/cli/README.md

@@ -6,16 +6,18 @@ A powerful command-line interface for managing ToadStool workloads, monitoring r
 
 ## Installation
 
+Production binaries are distributed via **plasmidBin** — the NUCLEUS binary depot:
+
 ```bash
-cargo install toadstool-cli
+# plasmidBin auto-harvests from CI on every push to main.
+# Binary lands at /opt/toadstool/bin/toadstool (includes CLI).
 ```
 
-Or build from source:
+For development builds:
 
 ```bash
-git clone https://github.com/your-org/toadstool.git
-cd toadstool/crates/cli
-cargo install --path .
+cargo build -p toadstool-cli
+# Binary: target/debug/toadstool
 ```
 
 ## Quick Start

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

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

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

@@ -33,8 +33,19 @@ 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?;
+    serve_unix_prebound(handler, listener).await
+}
+
+/// Bind a Unix socket listener early (Wave 49 startup optimization).
+///
+/// Returns the bound listener so the caller can pass it to
+/// [`serve_unix_prebound`] after constructing the handler. This
+/// ensures `connect()` succeeds as soon as the socket path exists,
+/// even before the full handler is ready.
+pub async fn prebind_unix_listener(socket_path: &std::path::Path) -> ServerResult<UnixListener> {
     info!(
-        "Starting pure JSON-RPC 2.0 server on Unix socket: {:?}",
+        "Pre-binding JSON-RPC Unix socket: {:?}",
         socket_path
     );
 
@@ -45,18 +56,17 @@ pub async fn serve_unix(handler: Arc<JsonRpcHandler>, socket_path: PathBuf) -> S
                 parent.display()
             ))
         })?;
-        info!("Ensured JSON-RPC socket directory exists: {:?}", parent);
     }
 
     if socket_path.exists() {
         warn!("Removing old JSON-RPC socket: {:?}", socket_path);
-        tokio::fs::remove_file(&socket_path)
+        tokio::fs::remove_file(socket_path)
             .await
             .map_err(|e| ServerError::Network(e.to_string()))?;
     }
 
     let listener =
-        UnixListener::bind(&socket_path).map_err(|e| ServerError::Network(e.to_string()))?;
+        UnixListener::bind(socket_path).map_err(|e| ServerError::Network(e.to_string()))?;
 
     #[cfg(unix)]
     {
@@ -68,30 +78,36 @@ pub async fn serve_unix(handler: Arc<JsonRpcHandler>, socket_path: PathBuf) -> S
                     u32::from_str_radix(s.trim_start_matches("0o").trim_start_matches('0'), 8).ok()
                 })
                 .unwrap_or(0o600);
-        let mut perms = tokio::fs::metadata(&socket_path)
+        let mut perms = tokio::fs::metadata(socket_path)
             .await
             .map_err(|e| ServerError::Internal(e.to_string()))?
             .permissions();
         perms.set_mode(mode);
-        tokio::fs::set_permissions(&socket_path, perms)
+        tokio::fs::set_permissions(socket_path, perms)
             .await
             .map_err(|e| ServerError::Internal(e.to_string()))?;
         info!("Set JSON-RPC socket permissions to {mode:04o}");
     }
 
+    info!("✅ JSON-RPC socket bound: {:?}", socket_path);
+    Ok(listener)
+}
+
+/// 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,
+) -> ServerResult<()> {
     let env = toadstool_common::primal_sockets::SocketPathEnv::from_env();
     let btsp_required = toadstool_common::primal_sockets::is_btsp_required(&env);
 
     if btsp_required {
-        info!(
-            "✅ BTSP mode: length-prefixed framing on: {:?}",
-            socket_path
-        );
+        info!("✅ BTSP mode active on pre-bound socket");
     } else {
-        info!(
-            "✅ Pure JSON-RPC 2.0 server (NDJSON) listening on: {:?}",
-            socket_path
-        );
+        info!("✅ Pure JSON-RPC 2.0 server (NDJSON) accepting on pre-bound socket");
     }
 
     loop {

crates/server/src/pure_jsonrpc/mod.rs

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

crates/server/src/unibin/capabilities.rs

@@ -7,35 +7,45 @@
 //! across handlers (clone is refcount bump, not memcpy).
 
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 
 static CACHED_CAPABILITIES: std::sync::OnceLock<Vec<Arc<str>>> = std::sync::OnceLock::new();
+static GPU_DISCOVERY_STARTED: AtomicBool = AtomicBool::new(false);
 
 /// Query local GPU and compute capabilities.
 ///
 /// Uses toadstool-sysmon and wgpu for pure Rust discovery (zero C).
 /// Returns `Arc<str>` per capability — clone is cheap (refcount bump).
 ///
-/// Results are cached after first call (hardware doesn't change at runtime).
+/// **Lazy GPU discovery (Wave 49 startup optimization):**
+/// First call returns a fast baseline (CPU, memory, orchestration) and
+/// spawns wgpu GPU enumeration in the background. Subsequent calls after
+/// GPU discovery completes return the full cached result including GPU
+/// capabilities. This prevents wgpu's Vulkan driver init (1–5s) from
+/// blocking the server startup path.
 pub async fn query_local_capabilities() -> Vec<Arc<str>> {
     if let Some(cached) = CACHED_CAPABILITIES.get() {
         return cached.clone();
     }
-    let caps = query_local_capabilities_uncached().await;
-    CACHED_CAPABILITIES.get_or_init(|| caps).clone()
+
+    // Kick off GPU discovery in background (once)
+    if !GPU_DISCOVERY_STARTED.swap(true, Ordering::Relaxed) {
+        tokio::spawn(async {
+            let full = discover_all_capabilities().await;
+            let _ = CACHED_CAPABILITIES.set(full);
+        });
+    }
+
+    query_baseline_capabilities()
 }
 
-/// Uncached capability detection — scans hardware every call.
-#[expect(
-    clippy::unused_async,
-    reason = "async required when gpu-discovery feature enables wgpu adapter enumeration"
-)]
-async fn query_local_capabilities_uncached() -> Vec<Arc<str>> {
+/// Fast baseline: CPU + memory + orchestration — no GPU probing.
+fn query_baseline_capabilities() -> Vec<Arc<str>> {
     let mut capabilities: Vec<Arc<str>> = vec![Arc::from("compute"), Arc::from("cpu")];
 
     let cpus = toadstool_sysmon::cpu_count();
     if cpus >= 16 {
         capabilities.push(Arc::from("high-core-count"));
-        tracing::info!("High core count detected: {cpus} cores");
     }
 
     if let Ok(mem) = toadstool_sysmon::memory_info() {
@@ -46,10 +56,25 @@ async fn query_local_capabilities_uncached() -> Vec<Arc<str>> {
         let total_memory_gb = mem.total as f64 / 1024.0 / 1024.0 / 1024.0;
         if total_memory_gb >= 32.0 {
             capabilities.push(Arc::from("high-memory"));
-            tracing::info!("High memory detected: {total_memory_gb:.1} GB");
         }
     }
 
+    capabilities.push(Arc::from("orchestration"));
+    capabilities
+}
+
+/// Full capability detection including GPU discovery via wgpu.
+///
+/// Runs in a background task to avoid blocking server startup.
+#[expect(
+    clippy::unused_async,
+    reason = "async required when gpu-discovery feature enables wgpu adapter enumeration"
+)]
+async fn discover_all_capabilities() -> Vec<Arc<str>> {
+    let mut capabilities = query_baseline_capabilities();
+
+    tracing::info!("🔍 Starting GPU discovery (background)...");
+
     #[cfg(feature = "gpu-discovery")]
     {
         let adapters = wgpu::Instance::default().enumerate_adapters(wgpu::Backends::all());
@@ -104,8 +129,7 @@ async fn query_local_capabilities_uncached() -> Vec<Arc<str>> {
         tracing::info!("GPU discovery disabled (compile with --features gpu-discovery)");
     }
 
-    capabilities.push(Arc::from("orchestration"));
-    tracing::info!("📊 Local capabilities: {:?}", capabilities);
+    tracing::info!("📊 Full capabilities: {:?}", capabilities);
     capabilities
 }
 

crates/server/src/unibin/execution.rs

@@ -7,7 +7,7 @@ use tracing::{error, info, warn};
 
 use crate::CoordinatorExecutor;
 use crate::errors::{ServerError, ServerResult};
-use crate::pure_jsonrpc::{JsonRpcHandler, serve_tcp, serve_unix};
+use crate::pure_jsonrpc::{JsonRpcHandler, serve_tcp, serve_unix, serve_unix_prebound};
 use crate::tarpc_server::{StandaloneExecutor, ToadStoolTarpcServer, WorkloadExecutorDispatch};
 
 use super::capabilities;
@@ -165,7 +165,10 @@ pub async fn create_executor(
     }
 }
 
-/// Start servers with Unix socket or TCP fallback
+/// Start servers with Unix socket or TCP fallback.
+///
+/// When `jsonrpc_listener` is `Some`, the JSON-RPC server uses the pre-bound
+/// listener (Wave 49 fast-bind optimization). Otherwise it binds its own.
 ///
 /// # Errors
 ///
@@ -177,8 +180,8 @@ pub async fn start_servers_with_fallback(
     jsonrpc_socket: PathBuf,
     tcp_port: Option<u16>,
     cfg: &UnibinExecutionConfig,
+    jsonrpc_listener: Option<tokio::net::UnixListener>,
 ) -> ServerResult<()> {
-    // When --port is explicitly provided, always start TCP alongside Unix sockets (UniBin std).
     if let Some(port) = tcp_port {
         info!("   --port {port} specified: starting TCP JSON-RPC (UniBin standard)");
         let tcp_handler = Arc::clone(&jsonrpc_handler);
@@ -192,7 +195,7 @@ pub async fn start_servers_with_fallback(
 
     info!("   Trying Unix socket IPC (optimal)...");
 
-    match try_unix_servers(&server, &jsonrpc_handler, &socket_path, &jsonrpc_socket).await {
+    match try_unix_servers(&server, &jsonrpc_handler, &socket_path, &jsonrpc_socket, jsonrpc_listener).await {
         Ok(()) => Ok(()),
         Err(e) => {
             let error_str = e.to_string();
@@ -213,13 +216,16 @@ async fn try_unix_servers(
     jsonrpc_handler: &Arc<JsonRpcHandler>,
     socket_path: &PathBuf,
     jsonrpc_socket: &PathBuf,
+    jsonrpc_listener: Option<tokio::net::UnixListener>,
 ) -> ServerResult<()> {
     if let Some(parent) = socket_path.parent() {
         tokio::fs::create_dir_all(parent)
             .await
             .map_err(|e| ServerError::Initialization(e.to_string()))?;
     }
-    if let Some(parent) = jsonrpc_socket.parent() {
+    if jsonrpc_listener.is_none()
+        && let Some(parent) = jsonrpc_socket.parent()
+    {
         tokio::fs::create_dir_all(parent)
             .await
             .map_err(|e| ServerError::Initialization(e.to_string()))?;
@@ -228,7 +234,9 @@ async fn try_unix_servers(
     if let Err(e) = tokio::fs::remove_file(socket_path).await {
         tracing::debug!("Socket cleanup: {e}");
     }
-    if let Err(e) = tokio::fs::remove_file(jsonrpc_socket).await {
+    if jsonrpc_listener.is_none()
+        && let Err(e) = tokio::fs::remove_file(jsonrpc_socket).await
+    {
         tracing::debug!("Socket cleanup: {e}");
     }
 
@@ -237,12 +245,20 @@ async fn try_unix_servers(
     info!("   Socket (tarpc): {:?}", socket_path);
 
     let jsonrpc_handler = Arc::clone(jsonrpc_handler);
-    let jsonrpc_socket_clone = jsonrpc_socket.clone();
-    tokio::spawn(async move {
-        if let Err(e) = serve_unix(jsonrpc_handler, jsonrpc_socket_clone).await {
-            error!("JSON-RPC server error: {}", e);
-        }
-    });
+    if let Some(listener) = jsonrpc_listener {
+        tokio::spawn(async move {
+            if let Err(e) = serve_unix_prebound(jsonrpc_handler, listener).await {
+                error!("JSON-RPC server error: {}", e);
+            }
+        });
+    } else {
+        let jsonrpc_socket_clone = jsonrpc_socket.clone();
+        tokio::spawn(async move {
+            if let Err(e) = serve_unix(jsonrpc_handler, jsonrpc_socket_clone).await {
+                error!("JSON-RPC server error: {}", e);
+            }
+        });
+    }
 
     server.clone().serve_unix(socket_path).await?;
     Ok(())