fix(runner): align doctor exit with readiness

AI assistance: OpenAI GPT-5.6 Sol via OpenCode inspected the doctor/result contracts, implemented the exit semantics, and added focused tests. Chris Huber remains responsible for every line.

Author: Chris Huber

crates/homeboy-cli/src/commands/runner/doctor/mod.rs

@@ -75,7 +75,8 @@ pub fn run_with_options(
     }
 
     report.status = checks::overall_status(&report.checks);
-    Ok((report, 0))
+    let exit_code = report.status.operational_exit_code();
+    Ok((report, exit_code))
 }
 
 fn runner_summary(

crates/homeboy-cli/src/commands/runner/doctor/tests/shape.rs

@@ -64,3 +64,21 @@ fn overall_status_promotes_errors_over_warnings() {
     ];
     assert_eq!(checks::overall_status(&checks), RunnerDoctorStatus::Error);
 }
+
+#[test]
+fn operational_exit_code_matches_the_doctor_readiness_verdict() {
+    for (scenario, status, expected_exit_code) in [
+        ("healthy", RunnerDoctorStatus::Ok, 0),
+        ("degraded", RunnerDoctorStatus::Warning, 0),
+        // A disconnected runner with a recoverable daemon is still not ready
+        // until `--repair` has rerun its probe successfully.
+        ("disconnected_recoverable", RunnerDoctorStatus::Error, 1),
+        ("terminal_error", RunnerDoctorStatus::Error, 1),
+    ] {
+        assert_eq!(
+            status.operational_exit_code(),
+            expected_exit_code,
+            "{scenario}"
+        );
+    }
+}

crates/homeboy-cli/src/commands/runner/doctor/tests/tools.rs

@@ -75,7 +75,7 @@ fn local_doctor_honors_required_tool_errors() {
     )
     .expect("local doctor report");
 
-    assert_eq!(exit_code, 0);
+    assert_eq!(exit_code, 1);
     assert_eq!(report.status, RunnerDoctorStatus::Error);
     assert!(report.checks.iter().any(|check| {
         check.id == "tool.required.homeboy-definitely-missing-tool"

crates/homeboy-cli/src/commands/runner/doctor/types.rs

@@ -9,6 +9,17 @@ pub enum RunnerDoctorStatus {
     Error,
 }
 
+impl RunnerDoctorStatus {
+    /// The process result for a completed doctor report. Warnings remain
+    /// diagnostic-only; error-level checks make the runner not ready.
+    pub const fn operational_exit_code(self) -> i32 {
+        match self {
+            Self::Ok | Self::Warning => 0,
+            Self::Error => 1,
+        }
+    }
+}
+
 #[derive(Debug, Serialize)]
 pub struct RunnerDoctorOutput {
     pub variant: &'static str,

crates/homeboy-cli/src/commands/utils/response.rs

@@ -1433,6 +1433,33 @@ mod tests {
         assert!(value.get("subject_state").is_none());
     }
 
+    #[test]
+    fn doctor_readiness_verdict_serializes_consistently_with_the_envelope() {
+        for (scenario, doctor_status, exit_code, success, envelope_status) in [
+            ("healthy", "ok", 0, true, "succeeded"),
+            ("degraded", "warn", 0, true, "succeeded"),
+            ("disconnected_recoverable", "error", 1, false, "failed"),
+            ("terminal_error", "error", 1, false, "failed"),
+        ] {
+            let response = cli_response_for_json_result_for_identity(
+                &Ok(json!({
+                    "command": "runner.doctor",
+                    "status": doctor_status,
+                    "checks": [{ "id": "daemon.recovery", "status": doctor_status }],
+                })),
+                exit_code,
+                &CommandIdentity::with_operation("runner", "doctor"),
+                None,
+            );
+            let value = serde_json::to_value(response).expect("serialize response");
+
+            assert_eq!(value["success"], success, "{scenario}");
+            assert_eq!(value["exit_code"], exit_code, "{scenario}");
+            assert_eq!(value["status"], envelope_status, "{scenario}");
+            assert_eq!(value["data"]["status"], doctor_status, "{scenario}");
+        }
+    }
+
     fn release_failure_payload(step_id: &str, step_type: &str) -> Value {
         json!({
             "command": "release",

docs/commands/runner.md

@@ -179,6 +179,8 @@ replace the session, or tear down its tunnel. Use `local`,
 `localhost`, or `self` to inspect this machine without creating a runner record.
 The JSON payload uses `command: "runner.doctor"` and includes `runner_id`,
 `status`, `capabilities`, and warning/error details when a capability probe fails.
+`status: "error"` means the runner is not ready and exits with status `1`; `ok`
+and non-blocking `warn` reports exit `0`. The command has no report-only mode.
 
 Use `doctor` before `connect` when you need to know whether Homeboy, Git, SSH,
 and the configured workspace root are usable on the target machine.