feat(api): wire container healthcheck observer end to end

[chrisgeo]

Summary

Implements the full healthcheck observer that populates ContainerSnapshot.health (the read-only field reserved by CHAOS-1319) by running the configured probe inside the running container, interpreting exit codes through a Docker-compatible state machine, and writing the result back through the ContainersService actor under a generation-gated update path.

This is the upstream-shaped staging PR for CHAOS-1381. Together with CHAOS-1319 (which reserves the SDK shape) it closes the loop for compose-spec depends_on.condition: service_healthy against compose-spec orchestrators.

Stacking

This branch is based on feat/chaos-1319-health-status so the HealthStatus enum and ContainerSnapshot.health field exist in the diff. CHAOS-1319 (PR #13) should land first or be batched with this one. The combined change is reviewable in a single pass; once #13 merges, this PR rebases cleanly onto main.

Architecture (per design consult)

                        ┌──────────────────────────┐
   bootstrap → .running │   ContainersService      │
                        │   (existing actor)       │
                        │   ContainerState now     │
                        │   carries healthGeneration│
                        └────────────┬─────────────┘
                              register
                                     ▼
                        ┌──────────────────────────┐
                        │   HealthMonitor (NEW)    │ ← per-container observer Task
                        │   mirrors ExitMonitor    │
                        └────────────┬─────────────┘
                              probe loop (interval, timeout)
                                     ▼
                        ┌──────────────────────────┐
                        │   HealthProber (NEW)     │ ← protocol; mockable
                        │   SandboxClientHealthProber │
                        │   reuses createProcess + │
                        │   startProcess + wait    │
                        └────────────┬─────────────┘
                              probe outcome
                                     ▼
                        ┌──────────────────────────┐
                        │  HealthStateMachine (NEW)│ ← pure value type
                        │  Docker-compatible flow  │
                        └────────────┬─────────────┘
                              status transition
                                     ▼
                        ContainersService.applyHealthUpdate
                              ↓
                        generation check + status==.running gate
                              ↓
                        snapshot.health mutation

Key decisions:

• Observer placement in a dedicated HealthMonitor actor (mirrors ExitMonitor); keeps ContainersService from growing further and provides a clean cancellation boundary.
• Probe execution through the existing createProcess / startProcess / wait path; no new XPC route added. Synthetic process id is __container_healthcheck_<UUID>. Stdio is intentionally not forwarded.
• Probe timeout enforced via task-group race against Task.sleep. Timed-out probes are killed with SIGKILL before the group drains so the wait() task can return.
• Generation-gated snapshot updates: every transition into .running bumps ContainerState.healthGeneration. Late callbacks from a previous container instance are dropped at applyHealthUpdate (gen mismatch + status check).

CLI surface

container run \
    --health-cmd \"redis-cli ping | grep -q PONG\" \
    --health-interval 5 \
    --health-timeout 2 \
    --health-retries 3 \
    --health-start-period 10 \
    --health-start-interval 1 \
    redis:latest

Flag	Effect
--health-cmd <shell>	Translates to [\"CMD-SHELL\", cmd]; runs via /bin/sh -c inside the container.
--health-interval <s>	Time between probes; default 30.
--health-timeout <s>	Per-probe deadline; default 30. Probe killed on timeout.
--health-retries <n>	Consecutive failures before unhealthy; default 3.
--health-start-period <s>	Grace window. Failures during this window do not count. First success during grace transitions immediately to healthy.
--health-start-interval <s>	Probe interval used while still inside the grace window.
--no-healthcheck	Sets test=[\"NONE\"]; bypasses any image-baked healthcheck.

The richer [\"CMD\", \"exec\", \"arg1\", ...] form is reachable via API clients that build Healthcheck directly (e.g. compose orchestrators) — CLI surface for CMD-form probes is follow-up work called out in the commit.

Wire compatibility

ContainerConfiguration.healthcheck is a new optional field, decoded with decodeIfPresent. Containers persisted by older daemons round-trip cleanly (covered by testLegacyContainerConfigurationDecodesWithoutHealthcheck). New CLI flags are independent and have no effect when omitted.

Known limitations (intentional, follow-up work)

• --health-cmd accepts only the shell form. CMD-form CLI surface is follow-up.
• Daemon restart does not rehydrate health state. Observers restart from .starting rather than persisting counters across daemon launches. Deliberate v1 scope per the design consult.
• Probe intervals are Foundation TimeInterval (Double seconds). Compose-spec duration strings ("30s", "1m30s") are parsed by the client.

Verification

• `swift build -c release` — clean on macOS 26 / Apple silicon.
• `swift test --filter 'HealthcheckTest|HealthStateMachineTest|HealthMonitorTest'` — 26/26 passing:
  • HealthcheckTest (12): shape parsing (CMD/CMD-SHELL/NONE), validation error paths, disable flag, probeInterval rule (start-interval inside grace only), legacy-config Codable round-trip regression.
  • HealthStateMachineTest (10): every transition documented in the design — initial state, success during grace, failure during grace, failures past grace toward retries, success resets counter, unhealthy recovers without restart, disabled machine ignores inputs, retries=0 corner case.
  • HealthMonitorTest (4): `ScriptedProber` actor + `StatusRecorder` ordered-update capture. Disabled-check single-callback, .starting → .healthy transition, consecutive-failure → .unhealthy, unregister-cancels-loop guarantee.

[linear]

CHAOS-1381 FR upstream: --health-cmd / --health-* CLI flags on container run