feat(engine,cli): apply preflight halts with NIX_NOT_INSTALLED when needed (#58)

Implements ADR-0012 decision 3: when a plan would dispatch a
UserEnvSwitch but `nix --version` fails, apply halts at preflight
(class 1, exit 2) before any snapshot or db sync. The CLI's hint is
the literal `pearlite bootstrap` invocation.

- pearlite-userenv::NixInstaller gains a `nix_installed()` probe
  method. LiveNixInstaller hoists the previously-private
  `nix_already_installed` body to satisfy it; `install_if_missing`
  now calls the public method instead. MockNixInstaller returns its
  `already` flag, so existing test fixtures are unchanged in
  behavior.
- pearlite-engine::ApplyContext gains a `nix_installer` field. The
  apply_plan body checks `needs_nix(plan)` (any UserEnvSwitch action)
  and probes via the adapter before pre-snapshot. New
  ApplyError::NixNotInstalled (preflight) and ApplyError::NixProbe
  (#[from] InstallerError) variants surface the failure modes.
- CLI dispatch's apply_error_payload maps the two variants to typed
  codes NIX_NOT_INSTALLED and APPLY_NIX_PROBE_FAILED with class
  "preflight" / exit 2, overriding the recorded-failure-class
  default since these errors halt before any FailureRef is written.
  The hint for NIX_NOT_INSTALLED is `pearlite bootstrap
  --installer-script <path>`.
- 20 engine test sites updated via make_ctx to thread the new field;
  the 3 injected-failure tests update their ApplyContext literals.
- Two new engine tests cover the preflight branch (halts before
  snapshot, no FailureRef) and the no-UserEnvSwitch path (nix probe
  is skipped entirely).

Tests: 316 passing (+2). Clippy clean. fmt clean. audit clean.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

crates/pearlite-cli/src/dispatch.rs

@@ -279,6 +279,7 @@ fn dispatch_apply(
         systemd: ctx.systemd.as_ref(),
         snapper: ctx.snapper.as_ref(),
         home_manager: ctx.home_manager.as_ref(),
+        nix_installer: ctx.nix_installer.as_ref(),
         snapper_config: opts.snapper_config,
         state_path: &ctx.state_path,
         failures_dir: &failures_dir,
@@ -928,24 +929,42 @@ fn apply_error_payload(
             "home-manager --version  # verify home-manager is reachable for the target user, then retry"
                 .to_owned(),
         ),
+        ApplyError::NixProbe(_) => (
+            "APPLY_NIX_PROBE_FAILED",
+            "nix --version  # verify the nix binary is healthy on PATH".to_owned(),
+        ),
+        ApplyError::NixNotInstalled => (
+            "NIX_NOT_INSTALLED",
+            "pearlite bootstrap --installer-script <path>  # ADR-0012".to_owned(),
+        ),
     };
 
-    let class_label = match default_class {
-        2 => "plan",
-        3 => "apply-recoverable",
-        4 => "apply-incoherent",
-        _ => "apply",
+    // NIX_NOT_INSTALLED and APPLY_NIX_PROBE_FAILED are preflight
+    // errors: apply_plan returns before any system mutation, so they
+    // don't write a FailureRef and don't follow the class-3/4
+    // recoverable taxonomy. Surface as class=preflight, exit=2.
+    let (class_label, exit_code, surfaced_class) = match err {
+        ApplyError::NixNotInstalled | ApplyError::NixProbe(_) => ("preflight", 2_u8, 1_u8),
+        _ => {
+            let label = match default_class {
+                2 => "plan",
+                3 => "apply-recoverable",
+                4 => "apply-incoherent",
+                _ => "apply",
+            };
+            (label, default_exit_code, default_class)
+        }
     };
 
     ErrorPayload {
         code: code.to_owned(),
         class: class_label.to_owned(),
-        exit_code: default_exit_code,
+        exit_code,
         message: format!("{err}"),
         hint,
         details: serde_json::json!({
             "plan_id": plan_id,
-            "failure_class": default_class,
+            "failure_class": surfaced_class,
         }),
     }
 }