S225: PG-62 — health.liveness fast-path + startup reorder

health.liveness returns {"status":"starting"} during initialization
and {"status":"alive"} once fully ready (via Arc<AtomicBool> readiness
flag). health.readiness likewise transitions "starting" → "ready".

Discovery registration + biomeOS scan moved after listener spawn so
the socket accepts connections immediately. Recommended caller timeout:
≥3 seconds (documented in README). BearDog crypto.sign_contract
(PG-60+) tracked in NEXT_STEPS for Phase 60+.

Pre-existing clippy lint in auto_config/discoverer.rs fixed
(items_after_statements).

+5 tests. 22,843 workspace tests, 0 failures.

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

Author: BiomeOS Developer

CONTEXT.md

@@ -30,7 +30,7 @@ ToadStool is the **Layer 0** hardware substrate that other primals and springs d
   - Family: `compute-{family_id}.sock` / `compute-{family_id}-tarpc.sock`
 - **Peer primals**: Resolved at runtime via capability IDs and Unix-socket discovery (e.g. `capability.discover`, `resolve_capability_socket_fallback`) — not hardcoded URLs or legacy per-primal env manifests
 - **Discovery hierarchy** (primalSpring cross-cutting): Songbird `ipc.resolve` → biomeOS `capability.discover` → UDS filesystem convention → socket registry → TCP probing. toadStool implements tiers 1–4; TCP probing (tier 5) not used for local IPC
-- **Tests**: 22,838 (7,896+ lib-only, 0 failures, unlimited parallelism)
+- **Tests**: 22,843 (7,896+ lib-only, 0 failures, unlimited parallelism)
 - **Unsafe**: 46 blocks (all in hw-safe/GPU/VFIO/display/plugin containment, all SAFETY-documented; reconciled S221); workspace `unsafe_code = "deny"`, 41 crates `forbid` + 5 hw crates with narrow `#[allow(unsafe_code, reason)]`; all lint attrs have `reason =` (S211+S213)
 - **async-trait**: DEPRECATED — fully removed and banned in `deny.toml` (S203r); transitive only via axum/config/wiggle
 - **deny.toml**: `ring` + `async-trait` + `zstd-sys` bans active (ecoBin v3 compliant)

DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # ToadStool Documentation Hub
 
-**Last Updated**: May 2026 — S224
+**Last Updated**: May 2026 — S225
 
 ---
 
@@ -30,12 +30,12 @@ These root documents were **fully resolved** and **fossilized** in wateringHole
 
 ---
 
-## Current State (S224 — May 2026)
+## Current State (S225 — 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.
 
-- **22,838 tests** (7,896+ lib-only), 0 failures, 0 clippy warnings, 0 fmt diffs. Full workspace concurrent test suite.
-- **65 JSON-RPC methods** (incl. `compute.execute` direct route S203f). Wire Standard L3 (partial): `cost_estimates`, `operation_dependencies`. IPC compliant (`health.liveness` → `{"status":"alive"}`, `health.readiness` → ready+version, `health.check` full envelope, `capabilities.list`, `identity.get`).
+- **22,843 tests** (7,896+ lib-only), 0 failures, 0 clippy warnings, 0 fmt diffs. Full workspace concurrent test suite.
+- **65 JSON-RPC methods** (incl. `compute.execute` direct route S203f). Wire Standard L3 (partial): `cost_estimates`, `operation_dependencies`. IPC compliant (`health.liveness` → `{"status":"starting"|"alive"}` with PG-62 fast-path, `health.readiness` → `"starting"|"ready"`+version, `health.check` full envelope, `capabilities.list`, `identity.get`). **Recommended caller timeout: ≥3 seconds** for health probes during startup.
 - **Dual-socket IPC** — `compute.sock` (JSON-RPC primary, biomeOS routes here) + `compute-tarpc.sock` (tarpc hot-path). Override: `TOADSTOOL_SOCKET` / `TOADSTOOL_TARPC_SOCKET`. Family: `compute-{fid}.sock` / `compute-{fid}-tarpc.sock`.
 - **Pipeline dispatch** — `compute.dispatch.pipeline.submit` + `.status` for ordered multi-stage workloads (DAG, topological sort, result forwarding). Resolves neuralSpring PG-05.
 - **Capability-based everywhere**: 0 production hardcoded primal names, 0 production mocks, 0 production unwraps, 0 TODOs/FIXMEs. All primal references use `PRIMAL_NAME` constant or capability identifiers.

NEXT_STEPS.md

@@ -1,8 +1,8 @@
 # ToadStool -- Next Steps
 
-**Updated**: May 2026 — S224 (PG-55: --bind Flag + Localhost Default)
-**Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | tests verified (22,833 workspace, 0 failures) | **~65 JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | **Zero production panics/expects** | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **46 unsafe blocks** (all in hw containment, all SAFETY-documented, reconciled S221) | **0 production TODOs** | **rustix 1.x workspace-wide** | **capability-based primal references (no hardcoded names, S221)** | **`async-trait` DEPRECATED** (banned in `deny.toml`) | **`deny.toml` ring + async-trait + zstd-sys bans active** | **BTSP Phase 3 encrypted channel (ChaCha20-Poly1305, S215)** | **BTSP Phase 3 transport switch verified (S218)** | **BTSP handshake bounded + connection-reused** (PG-46 resolved, S214) | **All lint attrs with reason (S211+S213)** | **Auth issuer capability-based (S209)** | **Self-registration with Songbird (S207)** | **Encrypted compute dispatch (Phase 55)** | **Display Phase 2 (petalTongue IPC)** | **BTSP JSON-line relay (Phase 45c)** | **Orchestrator lock-panic-free (S213)**
-**Latest**: S224 — PG-55: `--bind host:port` flag on `server`/`daemon` subcommands (follows barraCuda pattern). TCP bind default changed from `0.0.0.0` (all interfaces) to `127.0.0.1` (loopback only). `TOADSTOOL_BIND_ADDRESS` env override preserved. +5 tests. 22,838 tests, 0 failures.
+**Updated**: May 2026 — S225 (PG-62: Health Liveness Fast-Path + Startup Reorder)
+**Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | tests verified (22,843 workspace, 0 failures) | **~65 JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | **Zero production panics/expects** | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **46 unsafe blocks** (all in hw containment, all SAFETY-documented, reconciled S221) | **0 production TODOs** | **rustix 1.x workspace-wide** | **capability-based primal references (no hardcoded names, S221)** | **`async-trait` DEPRECATED** (banned in `deny.toml`) | **`deny.toml` ring + async-trait + zstd-sys bans active** | **BTSP Phase 3 encrypted channel (ChaCha20-Poly1305, S215)** | **BTSP Phase 3 transport switch verified (S218)** | **BTSP handshake bounded + connection-reused** (PG-46 resolved, S214) | **All lint attrs with reason (S211+S213)** | **Auth issuer capability-based (S209)** | **Self-registration with Songbird (S207)** | **Encrypted compute dispatch (Phase 55)** | **Display Phase 2 (petalTongue IPC)** | **BTSP JSON-line relay (Phase 45c)** | **Orchestrator lock-panic-free (S213)** | **Health liveness fast-path (PG-62, S225)**
+**Latest**: S225 — PG-62: `health.liveness` fast-path returns `{"status":"starting"}` during initialization, `{"status":"alive"}` once ready. Discovery registration moved after listener spawn. Recommended caller timeout: ≥3s. BearDog `crypto.sign_contract` (PG-60+) tracked for Phase 60+. +5 tests. 22,843 tests, 0 failures.
 
 ---
 
@@ -91,6 +91,7 @@ names directly. Deprecated API definitions retained for backward compatibility o
 | Sovereign compiler Phase 4+ | barraCuda team | naga-IR optimizer, register pressure, peepholes |
 | barraCuda budding Phases 1-4 | barraCuda team | API audit, SemVer 1.0, Springs rewire |
 | ComputeDispatch migration (D-CD) | barraCuda team | 144/280+ done; ~139 remaining; lives in barraCuda crate |
+| `crypto.sign_contract` (PG-60+) | BearDog team | Cross-family ionic bond contract signing — expose as JSON-RPC method (proposer, acceptor, capabilities, duration). primalSpring `bonding::ionic_rpc` ready to consume. Phase 60+, no urgency. |
 
 ---
 

README.md

@@ -42,7 +42,7 @@ Nest    = Tower  + Storage            <- storage
 | `cargo fmt --all -- --check` | 0 diffs |
 | `cargo clippy --workspace --all-targets -- -D warnings` | 0 warnings |
 | `cargo doc --workspace --no-deps` (RUSTDOCFLAGS="-D warnings") | 0 warnings |
-| `cargo test --workspace` | **22,838 tests, 0 failures** (7,896+ lib-only), **~222** ignored (hardware-gated); full workspace ~7m |
+| `cargo test --workspace` | **22,843 tests, 0 failures** (7,896+ lib-only), **~222** ignored (hardware-gated); full workspace ~7m |
 | Doctests | All passing (common, core, server, cli, testing, display) |
 | Standalone clone test | Pull to any machine, `cargo test` works (GPU-optional, CPU fallback, device-lost resilient) |
 | `unsafe` blocks | **46 actual** (all in hw-safe/GPU/VFIO/display/plugin containment crates); all SAFETY-documented (S204, reconciled S221); workspace `unsafe_code = "deny"`, **41 crates `forbid`** + 5 hw crates with narrow `#[allow(unsafe_code, reason)]`; **all lint attrs have `reason =`** (S211+S213) |
@@ -145,6 +145,16 @@ HDMI Tx    V4L2 Rx    Serial     TransportRouter
 - **Storage service integration** -- real JSON-RPC `storage.artifact.store`/`retrieve` with graceful fallback
 - **Real-time events**: `compute.status` JSON-RPC polling or biomeOS/coordination service for event streaming
 
+### Health Probe Timeouts (PG-62)
+
+Callers probing `health.liveness` should use a timeout of **≥3 seconds** (recommended: 5s for composition startup). During initialization, `health.liveness` returns `{"status":"starting"}` until the server is fully ready (discovery registered, biomeOS scanned), then transitions to `{"status":"alive"}`. The socket accepts connections immediately upon listener bind — before executor initialization completes — so callers receive a fast response even during cold start. If BTSP handshake is required, add its budget (5s default, overridable via `BTSP_HANDSHAKE_TIMEOUT_SECS`).
+
+| Probe | During init | After ready |
+|-------|-------------|-------------|
+| `health.liveness` | `{"status":"starting"}` | `{"status":"alive"}` |
+| `health.readiness` | `{"status":"starting","version":"..."}` | `{"status":"ready","version":"..."}` |
+| `health.check` | Full envelope (always `"alive"`) | Full envelope |
+
 ### JSON-RPC Methods (~67 dynamically built; S186)
 
 Surface trimmed to hardware orchestration and IPC boundaries. **Removed from this repo** (S169): `inference.*` / Ollama-style AI (→ intelligence service), **`shader.compile.*`** (→ visualization service), **`science.*`** / **`ecology.*`** / **`discovery.*`** / **`deploy.*`** relays (→ orchestration and peers). **Kept**: **`shader.dispatch`** (dispatch compiled binary to GPU; compile happens in visualization service).
@@ -247,7 +257,7 @@ toadStool/
 | Clippy pedantic warnings | 0 (workspace-wide `clippy::pedantic` clean; `#[expect]` evolution S131+) |
 | Doc warnings | 0 |
 | Build warnings | 0 |
-| Workspace tests | **22,833**, 0 failures (7,896+ lib-only) |
+| Workspace tests | **22,843**, 0 failures (7,896+ lib-only) |
 | Lib-only line coverage | ~83.6% |
 | Full workspace test time | ~7m (unlimited parallelism, `cfg!(test)` fast timeouts; GPU crates have NVK resilience wrappers) |
 | `unsafe` blocks | **46 actual** (all in hw-safe/GPU/VFIO/display/plugin containment crates); all SAFETY-documented (S204, reconciled S221); workspace `unsafe_code = "deny"`, **41 crates `forbid`** + 5 hw crates with narrow `#[allow(unsafe_code, reason)]` |
@@ -269,12 +279,14 @@ toadStool/
 **We are still evolving.** barraCuda (separate primal) owns all math and shaders. ToadStool focuses on hardware discovery, capability probing, and workload orchestration. All 5 spring handoffs absorbed.
 
 ### Active / Next
-- **Test coverage** -- pushing toward 90% target; 22,833 tests; ~83.6% lib-only line (185K lines instrumented); remaining gap: hardware-dependent paths (VFIO, DRM, V4L2), specialty runtimes
+- **Test coverage** -- pushing toward 90% target; 22,843 tests; ~83.6% lib-only line (185K lines instrumented); remaining gap: hardware-dependent paths (VFIO, DRM, V4L2), specialty runtimes
 - **DF64 / ComputeDispatch** -- transferred to barraCuda team (S93); toadStool serves hardware capabilities
 - **Sovereign compiler Phase 4+** -- register pressure estimation, loop software pipelining (barraCuda)
 - **NUCLEUS crypto integration** -- compute payloads encrypted via Tower `crypto.encrypt`/`crypto.decrypt` (S205); **self-registration with Songbird** via `DISCOVERY_SOCKET` + `ipc.register` at startup (S207)
 
 ### Recently Completed
+- **S225 (May 7, 2026)**: **PG-62 — Health Liveness Fast-Path + Startup Reorder** — `health.liveness` now returns `{"status":"starting"}` during initialization and `{"status":"alive"}` once fully ready (via `Arc<AtomicBool>` readiness flag). `health.readiness` likewise returns `"starting"` → `"ready"`. Discovery registration + biomeOS scan moved **after** listener spawn so the socket accepts connections immediately. Recommended caller timeout: **≥3 seconds** (documented). BearDog cross-family `crypto.sign_contract` (PG-60+) tracked for Phase 60+. +5 tests. 22,843 tests.
+- **S224 (May 7, 2026)**: **PG-55 — `--bind` Flag + Localhost Default (Security)** — Added `--bind host:port` CLI flag to `server`/`daemon` subcommands. Default TCP bind changed from `0.0.0.0` to `127.0.0.1`. Priority: CLI `--bind` > `TOADSTOOL_BIND_ADDRESS` env > localhost default. +5 tests. 22,838 tests.
 - **S223 (May 6, 2026)**: **Deep Debt — Smart Refactor + Sleep Elimination + Test Speed** — Smart-refactored `btsp/json_line.rs` (905→478 LOC + `relay.rs` 255 + `negotiate.rs` 189; zero files >800 LOC). Eliminated 4 test sleeps: `thread::sleep` → deterministic time manipulation (backdated timestamps, `tokio::time::pause`). Evolved `intrusion.rs` to `tokio::time::Instant` for testable time. Fixed `auto_config` ecosystem discovery blocking 10s on mDNS daemon startup/shutdown and DNS resolution in tests — `cfg!(test)` early-returns skip network I/O (237 tests: 10.02s→0.24s, 41x speedup). Confirmed zero production `unwrap()`. Stale `/tmp/ecoPrimals/discovery/` comments evolved to capability-based language. +12 tests (resource_validator/analysis). 22,833 tests.
 - **S222 (May 5, 2026)**: **primalSpring ironGate Audit — Sandbox + Env Expansion + Specs + Discovery** — Gap 2: sandbox `working_dir` override via `trusted_directories` (was hardcoded `/tmp`). Gap 8: `${VAR}`/`$VAR` env expansion in workload TOMLs. `display.composite` + `transport.bridge` specs added (PG-42). Discovery hierarchy documented. `convert_security_context` now parses isolation level. +26 tests. 22,821 tests.
 - **S221 (May 4, 2026)**: **Deep Debt — Capability Names + Dep Hygiene + Stub Evolution + Coverage** — All `barraCuda/coralReef` primal names in errors/deprecations evolved to capability-based language. reqwest 0.12→0.13 (ring→aws-lc-rs). `verify_migration_success` dead code fixed. Unsafe count reconciled 49→46. +20 tests (daemon routes 11, zero_config config 9). 22,580 tests.
@@ -355,7 +367,7 @@ See [CHANGELOG.md](CHANGELOG.md) for full session-by-session detail.
 
 | ID | Description | Status |
 |----|-------------|--------|
-| D-COV | Test coverage → 90% | Active — 22,833 tests; ~83.6% lib-only line (185K instrumented); remaining gap: hardware-dependent paths (VFIO, DRM, V4L2, akida) |
+| D-COV | Test coverage → 90% | Active — 22,843 tests; ~83.6% lib-only line (185K instrumented); remaining gap: hardware-dependent paths (VFIO, DRM, V4L2, akida) |
 | D-BTSP-PHASE3 | BTSP encrypted post-handshake channel | **RESOLVED** (S215+S218) — ChaCha20-Poly1305 encrypted channel implemented, transport switch verified |
 
 ### Resolved (S94b)
@@ -398,7 +410,7 @@ See [DEBT.md](DEBT.md) for full register and evolution paths.
 
 ---
 
-**Last Updated**: May 2026 — S224 (PG-55: --bind Flag + Localhost Default). **22,838** workspace tests, 0 failures (7,884+ lib-only). ~83.6% lib-only line coverage (target 90%). **65 JSON-RPC methods** (direct) + semantic registry with **Wire Standard L3** (cost_estimates + operation_dependencies). AGPL-3.0-or-later. Zero C FFI deps (ecoBin v3.0). **46 unsafe blocks** (all in hw-safe/GPU/VFIO/display/plugin containment crates); all SAFETY-documented; workspace `unsafe_code = "deny"`, **41 crates `forbid`** + 5 hw crates with narrow `#[allow(unsafe_code, reason)]`. **Zero production panics/expects**. IPC-first JSON-RPC (dual-socket: `compute.sock` + `compute-tarpc.sock`). Rust 1.85+ (edition 2024, MSRV). **BTSP Phase 3 encrypted channel** (ChaCha20-Poly1305, S215; transport switch verified S218). **PG-46 resolved** (socket reuse, S214). **Self-registration** with Songbird via `DISCOVERY_SOCKET` (S207). **Capability-based discovery compliant** per `CAPABILITY_BASED_DISCOVERY_STANDARD.md` v1.2.
+**Last Updated**: May 2026 — S225 (PG-62: Health Liveness Fast-Path + Startup Reorder). **22,843** workspace tests, 0 failures (7,884+ lib-only). ~83.6% lib-only line coverage (target 90%). **65 JSON-RPC methods** (direct) + semantic registry with **Wire Standard L3** (cost_estimates + operation_dependencies). AGPL-3.0-or-later. Zero C FFI deps (ecoBin v3.0). **46 unsafe blocks** (all in hw-safe/GPU/VFIO/display/plugin containment crates); all SAFETY-documented; workspace `unsafe_code = "deny"`, **41 crates `forbid`** + 5 hw crates with narrow `#[allow(unsafe_code, reason)]`. **Zero production panics/expects**. IPC-first JSON-RPC (dual-socket: `compute.sock` + `compute-tarpc.sock`). Rust 1.85+ (edition 2024, MSRV). **BTSP Phase 3 encrypted channel** (ChaCha20-Poly1305, S215; transport switch verified S218). **PG-46 resolved** (socket reuse, S214). **Self-registration** with Songbird via `DISCOVERY_SOCKET` (S207). **Capability-based discovery compliant** per `CAPABILITY_BASED_DISCOVERY_STANDARD.md` v1.2.
 
 ---
 

crates/auto_config/src/ecosystem/discoverer.rs

@@ -293,13 +293,13 @@ impl EcosystemDiscoverer {
     /// Delegates to `toadstool_common::primal_integration::try_discover_via_mdns`
     /// which probes `_toadstool._tcp.local.` and filters by capability TXT records.
     pub(crate) fn discover_mdns_services() -> HashMap<String, ServiceInfo> {
+        use toadstool_common::primal_integration::try_discover_via_mdns;
+
         if cfg!(test) {
             debug!("Skipping mDNS probing in test mode");
             return HashMap::new();
         }
 
-        use toadstool_common::primal_integration::try_discover_via_mdns;
-
         let mut services = HashMap::new();
 
         let capability_keys = ["discovery", "crypto", "storage", "compute", "orchestration"];

crates/server/benches/jsonrpc_throughput.rs

@@ -2,6 +2,7 @@
 //! JSON-RPC handler throughput benchmarks (parse → dispatch → serialize).
 
 use std::sync::Arc;
+use std::sync::atomic::AtomicBool;
 
 use criterion::black_box;
 use criterion::{Criterion, criterion_group, criterion_main};
@@ -17,6 +18,7 @@ fn jsonrpc_handler() -> JsonRpcHandler {
         )),
         Arc::<str>::from("bench-1.0.0"),
         None,
+        Arc::new(AtomicBool::new(true)),
     )
 }
 

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

@@ -2,6 +2,7 @@
 //! Tests for pure JSON-RPC connection handling (`process_request`, TCP, Unix).
 
 use std::sync::Arc;
+use std::sync::atomic::AtomicBool;
 
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio::net::{TcpListener, TcpStream, UnixStream};
@@ -16,7 +17,7 @@ fn test_handler() -> JsonRpcHandler {
     let executor = Arc::new(WorkloadExecutorDispatch::Standalone(
         StandaloneExecutor::new(),
     ));
-    JsonRpcHandler::new(executor, "test-conn-1.0.0".to_string(), None)
+    JsonRpcHandler::new(executor, "test-conn-1.0.0".to_string(), None, Arc::new(AtomicBool::new(true)))
 }
 
 #[tokio::test]