feat(health-check): expose --no-health-check CLI flag + REST escape hatch

boxlite-ai#613 makes the per-box health check task default-on so the new
zombie-shim reaper (Issue boxlite-ai#523) has a watcher to piggy-back on. The
schema field `BoxOptions.advanced.health_check: Option<HealthCheckOptions>`
already lets Rust library users opt out via `None`, but CLI users
(`boxlite run` / `create`) and REST/SDK clients (Python, Node, Go all
route through `POST /v1/boxes`) had no way to express that choice —
exactly the gap boxlite-ai#597 hit for `cap_overrides`.

Surface plumbed end-to-end:

  - `ManagementFlags { no_health_check: bool }` — `--no-health-check`
    on `boxlite run` / `create`. When set, `apply_to` clears
    `opts.advanced.health_check = None`.
  - REST client-side `CreateBoxRequest` gets
    `health_check_disabled: Option<bool>`; `from_options` flips it to
    `Some(true)` only when the operator already disabled health check
    in the input options, so the wire form stays byte-identical for
    every other call.
  - Server-side `CreateBoxRequest` (in `cli/src/commands/serve/types.rs`,
    `#[serde(deny_unknown_fields)]`) gains the same field. The
    `build_box_options` mapper builds a manual `AdvancedBoxOptions`
    instead of falling through `..Default::default()`, then forces
    `health_check = None` iff the wire says so.

Three-state semantics for `health_check_disabled`:

  - `Some(true)` → explicit disable; box runs with no watcher, no
    zombie reaping (operator takes responsibility — documented inline).
  - `Some(false)` → "use the server default" (= currently `Some(...)`).
    Same effect as omitting the field, but documents the intent on
    the wire.
  - absent → server default. Pre-boxlite-ai#613 clients keep the legacy POST
    body shape and get the new default-on behaviour without code
    changes.

Seven unit tests cover the surface symmetrically:

  - CLI: `management_flags_no_health_check_clears_advanced_field` /
    `management_flags_no_health_check_unset_keeps_default_on` —
    flag-on clears, flag-off preserves; pre-asserts the baseline
    so a regression that broke the default-on schema would also fail.
  - REST client: `test_create_box_request_carries_health_check_disabled_on_the_wire` /
    `test_create_box_request_omits_health_check_disabled_when_default`
    — `None` in BoxOptions → `Some(true)` on the wire; `Some(default)`
    → field absent (backward-compat with pre-boxlite-ai#613 servers).
  - REST server: `build_box_options_health_check_disabled_true_clears_health_check` /
    `build_box_options_no_health_check_field_keeps_default_on` /
    `build_box_options_health_check_disabled_false_keeps_default_on`
    — three-state JSON → BoxOptions mapping, including the explicit
    "Some(false) means default" sentinel.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Author: G4614

src/boxlite/src/rest/types.rs

@@ -102,6 +102,12 @@ pub(crate) struct CreateBoxRequest {
     pub detach: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub security: Option<String>,
+    /// Disable the per-box health check (Issue #523: also disables
+    /// the async-death zombie reaper that piggybacks on health check).
+    /// Omitted when absent so existing clients keep the default-on
+    /// behaviour without changing their POST body shape.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub health_check_disabled: Option<bool>,
 }
 
 impl CreateBoxRequest {
@@ -128,6 +134,15 @@ impl CreateBoxRequest {
             Some(options.secrets.iter().map(CreateBoxSecret::from).collect())
         };
 
+        // Only set the wire field when the operator explicitly disabled
+        // health check. `None` on the wire = "use server default" (which
+        // is currently `Some(HealthCheckOptions::default())`).
+        let health_check_disabled = if options.advanced.health_check.is_none() {
+            Some(true)
+        } else {
+            None
+        };
+
         Self {
             name,
             image,
@@ -145,6 +160,7 @@ impl CreateBoxRequest {
             auto_remove: Some(options.auto_remove),
             detach: Some(options.detach),
             security: None, // TODO: map security preset
+            health_check_disabled,
         }
     }
 }
@@ -481,6 +497,7 @@ mod tests {
             auto_remove: Some(true),
             detach: None,
             security: None,
+            health_check_disabled: None,
         };
         let json = serde_json::to_string(&req).unwrap();
         assert!(json.contains("\"name\":\"mybox\""));
@@ -535,6 +552,52 @@ mod tests {
         );
     }
 
+    /// Wire serialization: when the operator disabled health check
+    /// (`options.advanced.health_check = None`), `from_options` flips
+    /// `health_check_disabled = Some(true)` on the wire body so the
+    /// server side actually receives the intent.
+    #[test]
+    fn test_create_box_request_carries_health_check_disabled_on_the_wire() {
+        use crate::runtime::advanced_options::AdvancedBoxOptions;
+        use crate::runtime::options::{BoxOptions, RootfsSpec};
+        let opts = BoxOptions {
+            rootfs: RootfsSpec::Image("alpine:latest".into()),
+            advanced: AdvancedBoxOptions {
+                health_check: None,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        let req = CreateBoxRequest::from_options(&opts, None);
+        assert_eq!(req.health_check_disabled, Some(true));
+        let json = serde_json::to_string(&req).unwrap();
+        assert!(
+            json.contains("\"health_check_disabled\":true"),
+            "explicit disable must appear on the wire; got: {json}"
+        );
+    }
+
+    /// Backward compat: a `BoxOptions` with the default health_check
+    /// (i.e. `Some(HealthCheckOptions::default())`) omits the wire
+    /// field entirely — old clients/servers that don't know about
+    /// `health_check_disabled` keep behaving exactly as before.
+    #[test]
+    fn test_create_box_request_omits_health_check_disabled_when_default() {
+        use crate::runtime::options::{BoxOptions, RootfsSpec};
+        let opts = BoxOptions {
+            rootfs: RootfsSpec::Image("alpine:latest".into()),
+            // Don't touch `advanced` — uses default (health_check on).
+            ..Default::default()
+        };
+        let req = CreateBoxRequest::from_options(&opts, None);
+        assert_eq!(req.health_check_disabled, None);
+        let json = serde_json::to_string(&req).unwrap();
+        assert!(
+            !json.contains("health_check_disabled"),
+            "wire form must omit the field when default health check is in effect; got: {json}"
+        );
+    }
+
     #[test]
     fn test_create_box_request_from_options_disabled_network() {
         use crate::runtime::options::{BoxOptions, NetworkSpec, RootfsSpec};

src/cli/src/cli.rs

@@ -693,12 +693,24 @@ pub struct ManagementFlags {
     /// Automatically remove the box when it exits
     #[arg(long)]
     pub rm: bool,
+
+    /// Disable the per-box health check (Issue #523: also disables the
+    /// async-death zombie reaper that piggybacks on the health-check
+    /// loop). Use when the box is so short-lived or low-priority that
+    /// the 30 s background tick isn't worth its cost — typical case:
+    /// very large fleets where the operator runs their own monitoring
+    /// and accepts having to clean up zombies if a shim dies asynchronously.
+    #[arg(long = "no-health-check")]
+    pub no_health_check: bool,
 }
 
 impl ManagementFlags {
     pub fn apply_to(&self, opts: &mut BoxOptions) {
         opts.detach = self.detach;
         opts.auto_remove = self.rm;
+        if self.no_health_check {
+            opts.advanced.health_check = None;
+        }
     }
 }
 
@@ -708,6 +720,52 @@ mod tests {
     use std::fs;
     use tempfile::TempDir;
 
+    /// `--no-health-check` is the operator-level escape hatch for the
+    /// default-on health check introduced for zombie-shim reaping
+    /// (Issue #523 / #613). Setting it must clear
+    /// `BoxOptions.advanced.health_check` so the box-init pipeline
+    /// doesn't spawn a watcher task.
+    #[test]
+    fn management_flags_no_health_check_clears_advanced_field() {
+        let flags = ManagementFlags {
+            name: None,
+            detach: false,
+            rm: false,
+            no_health_check: true,
+        };
+        let mut opts = BoxOptions::default();
+        // Sanity-check the baseline default: health check is on at the
+        // schema level so `--no-health-check` actually has work to do.
+        assert!(
+            opts.advanced.health_check.is_some(),
+            "baseline must be health-check-on; otherwise this test isn't measuring the override"
+        );
+        flags.apply_to(&mut opts);
+        assert!(
+            opts.advanced.health_check.is_none(),
+            "--no-health-check must clear advanced.health_check"
+        );
+    }
+
+    /// Negative: leaving the flag off must leave the default-on
+    /// behaviour intact, so absence of the flag and presence of the
+    /// flag have distinguishable effects.
+    #[test]
+    fn management_flags_no_health_check_unset_keeps_default_on() {
+        let flags = ManagementFlags {
+            name: None,
+            detach: false,
+            rm: false,
+            no_health_check: false,
+        };
+        let mut opts = BoxOptions::default();
+        flags.apply_to(&mut opts);
+        assert!(
+            opts.advanced.health_check.is_some(),
+            "without --no-health-check the schema default (Some) must win"
+        );
+    }
+
     #[test]
     fn test_apply_env_vars_with_lookup() {
         let mut opts = BoxOptions::default();

src/cli/src/commands/serve/mod.rs

@@ -656,6 +656,16 @@ fn build_box_options(req: &CreateBoxRequest) -> Result<BoxOptions, boxlite::Boxl
         None => NetworkSpec::default(),
     };
 
+    // Resolve health_check policy:
+    // - `health_check_disabled = Some(true)` → explicit None (operator opt-out)
+    // - `Some(false)` / absent → keep the schema default (currently
+    //   `Some(HealthCheckOptions::default())`), so we let
+    //   `AdvancedBoxOptions::default()` win via `..Default::default()`.
+    let mut advanced = boxlite::AdvancedBoxOptions::default();
+    if req.health_check_disabled.unwrap_or(false) {
+        advanced.health_check = None;
+    }
+
     Ok(BoxOptions {
         rootfs,
         cpus: req.cpus,
@@ -669,6 +679,7 @@ fn build_box_options(req: &CreateBoxRequest) -> Result<BoxOptions, boxlite::Boxl
         user: req.user.clone(),
         auto_remove: req.auto_remove.unwrap_or(false),
         detach: req.detach.unwrap_or(true),
+        advanced,
         ..Default::default()
     })
 }
@@ -1017,6 +1028,54 @@ mod tests {
         assert!(constant_time_eq(b"", b""));
     }
 
+    /// `POST /v1/boxes` body with `health_check_disabled: true` flips
+    /// `advanced.health_check` to `None` in the resulting BoxOptions —
+    /// the SDK→REST→server path's escape hatch for the default-on
+    /// behaviour introduced in Issue #523 / #613.
+    #[test]
+    fn build_box_options_health_check_disabled_true_clears_health_check() {
+        let json = r#"{"image": "alpine:latest", "health_check_disabled": true}"#;
+        let req: super::types::CreateBoxRequest =
+            serde_json::from_str(json).expect("must deserialize");
+        let opts = build_box_options(&req).expect("build_box_options");
+        assert!(
+            opts.advanced.health_check.is_none(),
+            "explicit health_check_disabled=true must clear advanced.health_check"
+        );
+    }
+
+    /// Backward compat: a request body that omits `health_check_disabled`
+    /// (i.e. every pre-#613 client) gets the server-side default, which
+    /// after #613 is `Some(HealthCheckOptions::default())`. The empty
+    /// body must not silently strip health check.
+    #[test]
+    fn build_box_options_no_health_check_field_keeps_default_on() {
+        let json = r#"{"image": "alpine:latest"}"#;
+        let req: super::types::CreateBoxRequest =
+            serde_json::from_str(json).expect("legacy body must still deserialize");
+        let opts = build_box_options(&req).expect("build_box_options");
+        assert!(
+            opts.advanced.health_check.is_some(),
+            "default-on health check must survive a request that doesn't mention it"
+        );
+    }
+
+    /// `Some(false)` is the explicit "I want the default" sentinel —
+    /// behaves identically to omitting the field. Documents the wire
+    /// contract so a confused client setting it to false doesn't get
+    /// the disabled behaviour.
+    #[test]
+    fn build_box_options_health_check_disabled_false_keeps_default_on() {
+        let json = r#"{"image": "alpine:latest", "health_check_disabled": false}"#;
+        let req: super::types::CreateBoxRequest =
+            serde_json::from_str(json).expect("must deserialize");
+        let opts = build_box_options(&req).expect("build_box_options");
+        assert!(
+            opts.advanced.health_check.is_some(),
+            "health_check_disabled=false must be treated as 'use default' (= on)"
+        );
+    }
+
     /// Build an `ActiveExecution` backed by a stub `Execution` whose
     /// stdout/stderr/result channels we control from the test.
     fn make_test_active() -> (

src/cli/src/commands/serve/types.rs

@@ -39,6 +39,12 @@ pub(super) struct CreateBoxRequest {
     pub auto_remove: Option<bool>,
     #[serde(default)]
     pub detach: Option<bool>,
+    /// Disable the per-box health check (Issue #523: also disables the
+    /// async-death zombie reaper that piggybacks on health check).
+    /// `Some(true)` → disable; `Some(false)` / absent → server default
+    /// (currently `Some(HealthCheckOptions::default())`).
+    #[serde(default)]
+    pub health_check_disabled: Option<bool>,
 }
 
 #[derive(Deserialize)]