Make local environment failures diagnosable from the CLI

Add a non-interactive doctor subcommand that checks API key reachability, OAuth credential state, config files, git, MCP servers, network access, and system metadata in one structured report. The implementation reuses existing runtime/auth plumbing and adds focused tests for parsing and report behavior.

Also update stale runtime permission-mode tests so workspace verification reflects the current enum model rather than historical Prompt/Allow variants.

Constraint: Keep diagnostics dependency-free and reuse existing runtime/auth/MCP code
Rejected: Add a REPL-only slash command | diagnostics must work before a session starts
Rejected: Split checks into multiple subcommands | higher surface area with less troubleshooting value
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep doctor checks bounded and non-destructive; if future probes become slower or stateful, gate them explicitly
Tested: cargo fmt --all --check; cargo clippy --workspace --all-targets -- -D warnings; cargo test --workspace; cargo run -p rusty-claude-cli -- doctor
Not-tested: Positive live API-key validation path against a known-good production credential

rust/crates/rusty-claude-cli/src/main.rs

@@ -5,15 +5,16 @@ use std::collections::{BTreeMap, BTreeSet};
 use std::env;
 use std::fs;
 use std::io::{self, Read, Write};
-use std::net::TcpListener;
+use std::net::{TcpListener, TcpStream, ToSocketAddrs};
 use std::path::{Path, PathBuf};
 use std::process::Command;
-use std::time::{SystemTime, UNIX_EPOCH};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use api::{
-    resolve_startup_auth_source, AnthropicClient, AuthSource, ContentBlockDelta, InputContentBlock,
-    InputMessage, MessageRequest, MessageResponse, OutputContentBlock,
-    StreamEvent as ApiStreamEvent, ToolChoice, ToolDefinition, ToolResultContentBlock,
+    oauth_token_is_expired, resolve_startup_auth_source, AnthropicClient, ApiError, AuthSource,
+    ContentBlockDelta, InputContentBlock, InputMessage, MessageRequest, MessageResponse,
+    OutputContentBlock, StreamEvent as ApiStreamEvent, ToolChoice, ToolDefinition,
+    ToolResultContentBlock,
 };
 
 use commands::{
@@ -22,10 +23,11 @@ use commands::{
 use compat_harness::{extract_manifest, UpstreamPaths};
 use render::{Spinner, TerminalRenderer};
 use runtime::{
-    clear_oauth_credentials, generate_pkce_pair, generate_state, load_system_prompt,
-    parse_oauth_callback_request_target, save_oauth_credentials, ApiClient, ApiRequest,
-    AssistantEvent, CompactionConfig, ConfigLoader, ConfigSource, ContentBlock,
-    ConversationMessage, ConversationRuntime, MessageRole, OAuthAuthorizationRequest,
+    clear_oauth_credentials, generate_pkce_pair, generate_state, load_oauth_credentials,
+    load_system_prompt, parse_oauth_callback_request_target, save_oauth_credentials, ApiClient,
+    ApiRequest, AssistantEvent, CompactionConfig, ConfigLoader, ConfigSource, ContentBlock,
+    ConversationMessage, ConversationRuntime, McpClientBootstrap, McpClientTransport,
+    McpServerConfig, McpStdioProcess, MessageRole, OAuthAuthorizationRequest,
     OAuthTokenExchangeRequest, PermissionMode, PermissionPolicy, ProjectContext, RuntimeError,
     Session, TokenUsage, ToolError, ToolExecutor, UsageTracker,
 };
@@ -74,6 +76,7 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
             .run_turn_with_output(&prompt, output_format)?,
         CliAction::Login => run_login()?,
         CliAction::Logout => run_logout()?,
+        CliAction::Doctor => run_doctor()?,
         CliAction::Repl {
             model,
             allowed_tools,
@@ -106,6 +109,7 @@ enum CliAction {
     },
     Login,
     Logout,
+    Doctor,
     Repl {
         model: String,
         allowed_tools: Option<AllowedToolSet>,
@@ -230,6 +234,7 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
         "system-prompt" => parse_system_prompt_args(&rest[1..]),
         "login" => Ok(CliAction::Login),
         "logout" => Ok(CliAction::Logout),
+        "doctor" => Ok(CliAction::Doctor),
         "prompt" => {
             let prompt = rest[1..].join(" ");
             if prompt.trim().is_empty() {
@@ -520,6 +525,627 @@ fn wait_for_oauth_callback(
     Ok(callback)
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum DiagnosticLevel {
+    Ok,
+    Warn,
+    Fail,
+}
+
+impl DiagnosticLevel {
+    const fn label(self) -> &'static str {
+        match self {
+            Self::Ok => "OK",
+            Self::Warn => "WARN",
+            Self::Fail => "FAIL",
+        }
+    }
+
+    const fn is_failure(self) -> bool {
+        matches!(self, Self::Fail)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct DiagnosticCheck {
+    name: &'static str,
+    level: DiagnosticLevel,
+    summary: String,
+    details: Vec<String>,
+}
+
+impl DiagnosticCheck {
+    fn new(name: &'static str, level: DiagnosticLevel, summary: impl Into<String>) -> Self {
+        Self {
+            name,
+            level,
+            summary: summary.into(),
+            details: Vec::new(),
+        }
+    }
+
+    fn with_details(mut self, details: Vec<String>) -> Self {
+        self.details = details;
+        self
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum OAuthDiagnosticStatus {
+    Missing,
+    Valid,
+    ExpiredRefreshable,
+    ExpiredNoRefresh,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct ConfigFileCheck {
+    path: PathBuf,
+    exists: bool,
+    valid: bool,
+    note: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct DoctorReport {
+    checks: Vec<DiagnosticCheck>,
+}
+
+impl DoctorReport {
+    fn has_failures(&self) -> bool {
+        self.checks.iter().any(|check| check.level.is_failure())
+    }
+
+    fn render(&self) -> String {
+        let mut lines = vec!["Doctor diagnostics".to_string()];
+        let ok_count = self
+            .checks
+            .iter()
+            .filter(|check| check.level == DiagnosticLevel::Ok)
+            .count();
+        let warn_count = self
+            .checks
+            .iter()
+            .filter(|check| check.level == DiagnosticLevel::Warn)
+            .count();
+        let fail_count = self
+            .checks
+            .iter()
+            .filter(|check| check.level == DiagnosticLevel::Fail)
+            .count();
+        lines.push(format!(
+            "Summary\n  OK               {ok_count}\n  Warnings         {warn_count}\n  Failures         {fail_count}"
+        ));
+        lines.extend(self.checks.iter().map(render_diagnostic_check));
+        lines.join("\n\n")
+    }
+}
+
+fn render_diagnostic_check(check: &DiagnosticCheck) -> String {
+    let mut section = vec![format!(
+        "{}\n  Status           {}\n  Summary          {}",
+        check.name,
+        check.level.label(),
+        check.summary
+    )];
+    if !check.details.is_empty() {
+        section.push("  Details".to_string());
+        section.extend(check.details.iter().map(|detail| format!("    - {detail}")));
+    }
+    section.join("\n")
+}
+
+fn run_doctor() -> Result<(), Box<dyn std::error::Error>> {
+    let cwd = env::current_dir()?;
+    let config_loader = ConfigLoader::default_for(&cwd);
+    let config = config_loader.load();
+    let report = DoctorReport {
+        checks: vec![
+            check_api_key_validity(config.as_ref().ok()),
+            check_oauth_token_status(config.as_ref().ok()),
+            check_config_files(&config_loader, config.as_ref()),
+            check_git_availability(&cwd),
+            check_mcp_server_health(config.as_ref().ok()),
+            check_network_connectivity(),
+            check_system_info(&cwd, config.as_ref().ok()),
+        ],
+    };
+    println!("{}", report.render());
+    if report.has_failures() {
+        return Err("doctor found failing checks".into());
+    }
+    Ok(())
+}
+
+fn check_api_key_validity(config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
+    let api_key = match env::var("ANTHROPIC_API_KEY") {
+        Ok(value) if !value.trim().is_empty() => value,
+        Ok(_) | Err(env::VarError::NotPresent) => {
+            return DiagnosticCheck::new(
+                "API key validity",
+                DiagnosticLevel::Warn,
+                "ANTHROPIC_API_KEY is not set",
+            );
+        }
+        Err(error) => {
+            return DiagnosticCheck::new(
+                "API key validity",
+                DiagnosticLevel::Fail,
+                format!("failed to read ANTHROPIC_API_KEY: {error}"),
+            );
+        }
+    };
+
+    let request = MessageRequest {
+        model: config
+            .and_then(runtime::RuntimeConfig::model)
+            .unwrap_or(DEFAULT_MODEL)
+            .to_string(),
+        max_tokens: 1,
+        messages: vec![InputMessage {
+            role: "user".to_string(),
+            content: vec![InputContentBlock::Text {
+                text: "Reply with OK.".to_string(),
+            }],
+        }],
+        system: None,
+        tools: None,
+        tool_choice: None,
+        stream: false,
+    };
+    let runtime = match tokio::runtime::Runtime::new() {
+        Ok(runtime) => runtime,
+        Err(error) => {
+            return DiagnosticCheck::new(
+                "API key validity",
+                DiagnosticLevel::Fail,
+                format!("failed to create async runtime: {error}"),
+            );
+        }
+    };
+    match runtime
+        .block_on(AnthropicClient::from_auth(AuthSource::ApiKey(api_key)).send_message(&request))
+    {
+        Ok(response) => DiagnosticCheck::new(
+            "API key validity",
+            DiagnosticLevel::Ok,
+            "Anthropic API accepted the configured API key",
+        )
+        .with_details(vec![format!(
+            "request_id={} input_tokens={} output_tokens={}",
+            response.request_id.unwrap_or_else(|| "<none>".to_string()),
+            response.usage.input_tokens,
+            response.usage.output_tokens
+        )]),
+        Err(ApiError::Api { status, .. }) if status.as_u16() == 401 || status.as_u16() == 403 => {
+            DiagnosticCheck::new(
+                "API key validity",
+                DiagnosticLevel::Fail,
+                format!("Anthropic API rejected the API key with HTTP {status}"),
+            )
+        }
+        Err(error) => DiagnosticCheck::new(
+            "API key validity",
+            DiagnosticLevel::Warn,
+            format!("unable to conclusively validate the API key: {error}"),
+        ),
+    }
+}
+
+fn classify_oauth_status() -> Result<(OAuthDiagnosticStatus, Vec<String>), io::Error> {
+    let Some(token_set) = load_oauth_credentials()? else {
+        return Ok((OAuthDiagnosticStatus::Missing, vec![]));
+    };
+    let token = api::OAuthTokenSet {
+        access_token: token_set.access_token.clone(),
+        refresh_token: token_set.refresh_token.clone(),
+        expires_at: token_set.expires_at,
+        scopes: token_set.scopes.clone(),
+    };
+    let details = vec![format!(
+        "expires_at={} refresh_token={} scopes={}",
+        token
+            .expires_at
+            .map_or_else(|| "<none>".to_string(), |value| value.to_string()),
+        if token.refresh_token.is_some() {
+            "present"
+        } else {
+            "absent"
+        },
+        if token.scopes.is_empty() {
+            "<none>".to_string()
+        } else {
+            token.scopes.join(",")
+        }
+    )];
+    let status = if oauth_token_is_expired(&token) {
+        if token.refresh_token.is_some() {
+            OAuthDiagnosticStatus::ExpiredRefreshable
+        } else {
+            OAuthDiagnosticStatus::ExpiredNoRefresh
+        }
+    } else {
+        OAuthDiagnosticStatus::Valid
+    };
+    Ok((status, details))
+}
+
+fn check_oauth_token_status(config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
+    match classify_oauth_status() {
+        Ok((OAuthDiagnosticStatus::Missing, _)) => DiagnosticCheck::new(
+            "OAuth token status",
+            DiagnosticLevel::Warn,
+            "no saved OAuth credentials found",
+        ),
+        Ok((OAuthDiagnosticStatus::Valid, details)) => DiagnosticCheck::new(
+            "OAuth token status",
+            DiagnosticLevel::Ok,
+            "saved OAuth token is present and not expired",
+        )
+        .with_details(details),
+        Ok((OAuthDiagnosticStatus::ExpiredRefreshable, mut details)) => {
+            let refresh_ready = config.and_then(runtime::RuntimeConfig::oauth).is_some();
+            details.push(if refresh_ready {
+                "runtime OAuth config is present for refresh".to_string()
+            } else {
+                "runtime OAuth config is missing for refresh".to_string()
+            });
+            DiagnosticCheck::new(
+                "OAuth token status",
+                if refresh_ready {
+                    DiagnosticLevel::Warn
+                } else {
+                    DiagnosticLevel::Fail
+                },
+                "saved OAuth token is expired but includes a refresh token",
+            )
+            .with_details(details)
+        }
+        Ok((OAuthDiagnosticStatus::ExpiredNoRefresh, details)) => DiagnosticCheck::new(
+            "OAuth token status",
+            DiagnosticLevel::Fail,
+            "saved OAuth token is expired and cannot refresh",
+        )
+        .with_details(details),
+        Err(error) => DiagnosticCheck::new(
+            "OAuth token status",
+            DiagnosticLevel::Fail,
+            format!("failed to read saved OAuth credentials: {error}"),
+        ),
+    }
+}
+
+fn validate_config_file(path: &Path) -> ConfigFileCheck {
+    match fs::read_to_string(path) {
+        Ok(contents) => {
+            if contents.trim().is_empty() {
+                return ConfigFileCheck {
+                    path: path.to_path_buf(),
+                    exists: true,
+                    valid: true,
+                    note: "exists but is empty".to_string(),
+                };
+            }
+            match serde_json::from_str::<serde_json::Value>(&contents) {
+                Ok(serde_json::Value::Object(_)) => ConfigFileCheck {
+                    path: path.to_path_buf(),
+                    exists: true,
+                    valid: true,
+                    note: "valid JSON object".to_string(),
+                },
+                Ok(_) => ConfigFileCheck {
+                    path: path.to_path_buf(),
+                    exists: true,
+                    valid: false,
+                    note: "top-level JSON value is not an object".to_string(),
+                },
+                Err(error) => ConfigFileCheck {
+                    path: path.to_path_buf(),
+                    exists: true,
+                    valid: false,
+                    note: format!("invalid JSON: {error}"),
+                },
+            }
+        }
+        Err(error) if error.kind() == io::ErrorKind::NotFound => ConfigFileCheck {
+            path: path.to_path_buf(),
+            exists: false,
+            valid: true,
+            note: "not present".to_string(),
+        },
+        Err(error) => ConfigFileCheck {
+            path: path.to_path_buf(),
+            exists: true,
+            valid: false,
+            note: format!("unreadable: {error}"),
+        },
+    }
+}
+
+fn check_config_files(
+    config_loader: &ConfigLoader,
+    config: Result<&runtime::RuntimeConfig, &runtime::ConfigError>,
+) -> DiagnosticCheck {
+    let file_checks = config_loader
+        .discover()
+        .into_iter()
+        .map(|entry| validate_config_file(&entry.path))
+        .collect::<Vec<_>>();
+    let existing_count = file_checks.iter().filter(|check| check.exists).count();
+    let invalid_count = file_checks
+        .iter()
+        .filter(|check| check.exists && !check.valid)
+        .count();
+    let mut details = file_checks
+        .iter()
+        .map(|check| format!("{} => {}", check.path.display(), check.note))
+        .collect::<Vec<_>>();
+    match config {
+        Ok(runtime_config) => details.push(format!(
+            "merged load succeeded with {} loaded file(s)",
+            runtime_config.loaded_entries().len()
+        )),
+        Err(error) => details.push(format!("merged load failed: {error}")),
+    }
+    DiagnosticCheck::new(
+        "Config files",
+        if invalid_count > 0 || config.is_err() {
+            DiagnosticLevel::Fail
+        } else if existing_count == 0 {
+            DiagnosticLevel::Warn
+        } else {
+            DiagnosticLevel::Ok
+        },
+        format!(
+            "discovered {} candidate file(s), {} existing, {} invalid",
+            file_checks.len(),
+            existing_count,
+            invalid_count
+        ),
+    )
+    .with_details(details)
+}
+
+fn check_git_availability(cwd: &Path) -> DiagnosticCheck {
+    match Command::new("git").arg("--version").output() {
+        Ok(version_output) if version_output.status.success() => {
+            let version = String::from_utf8_lossy(&version_output.stdout)
+                .trim()
+                .to_string();
+            match Command::new("git")
+                .args(["rev-parse", "--show-toplevel"])
+                .current_dir(cwd)
+                .output()
+            {
+                Ok(root_output) if root_output.status.success() => DiagnosticCheck::new(
+                    "Git availability",
+                    DiagnosticLevel::Ok,
+                    "git is installed and the current directory is inside a repository",
+                )
+                .with_details(vec![
+                    version,
+                    format!(
+                        "repo_root={}",
+                        String::from_utf8_lossy(&root_output.stdout).trim()
+                    ),
+                ]),
+                Ok(_) => DiagnosticCheck::new(
+                    "Git availability",
+                    DiagnosticLevel::Warn,
+                    "git is installed but the current directory is not a repository",
+                )
+                .with_details(vec![version]),
+                Err(error) => DiagnosticCheck::new(
+                    "Git availability",
+                    DiagnosticLevel::Warn,
+                    format!("git is installed but repo detection failed: {error}"),
+                )
+                .with_details(vec![version]),
+            }
+        }
+        Ok(output) => DiagnosticCheck::new(
+            "Git availability",
+            DiagnosticLevel::Fail,
+            format!("git --version exited with status {}", output.status),
+        ),
+        Err(error) => DiagnosticCheck::new(
+            "Git availability",
+            DiagnosticLevel::Fail,
+            format!("failed to execute git: {error}"),
+        ),
+    }
+}
+
+fn check_one_mcp_server(
+    name: &str,
+    server: &runtime::ScopedMcpServerConfig,
+) -> (DiagnosticLevel, String) {
+    match &server.config {
+        McpServerConfig::Stdio(_) => {
+            let bootstrap = McpClientBootstrap::from_scoped_config(name, server);
+            let runtime = match tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+            {
+                Ok(runtime) => runtime,
+                Err(error) => {
+                    return (
+                        DiagnosticLevel::Fail,
+                        format!("{name}: runtime error: {error}"),
+                    )
+                }
+            };
+            let detail = runtime.block_on(async {
+                match tokio::time::timeout(Duration::from_secs(3), async {
+                    let mut process = McpStdioProcess::spawn(match &bootstrap.transport {
+                        McpClientTransport::Stdio(transport) => transport,
+                        _ => unreachable!("stdio bootstrap expected"),
+                    })?;
+                    let result = process
+                        .initialize(
+                            runtime::JsonRpcId::Number(1),
+                            runtime::McpInitializeParams {
+                                protocol_version: "2025-03-26".to_string(),
+                                capabilities: serde_json::Value::Object(serde_json::Map::new()),
+                                client_info: runtime::McpInitializeClientInfo {
+                                    name: "doctor".to_string(),
+                                    version: VERSION.to_string(),
+                                },
+                            },
+                        )
+                        .await;
+                    let _ = process.terminate().await;
+                    result
+                })
+                .await
+                {
+                    Ok(Ok(response)) => {
+                        if let Some(error) = response.error {
+                            (
+                                DiagnosticLevel::Fail,
+                                format!(
+                                    "{name}: initialize JSON-RPC error {} ({})",
+                                    error.message, error.code
+                                ),
+                            )
+                        } else if let Some(result) = response.result {
+                            (
+                                DiagnosticLevel::Ok,
+                                format!(
+                                    "{name}: ok (server {} {})",
+                                    result.server_info.name, result.server_info.version
+                                ),
+                            )
+                        } else {
+                            (
+                                DiagnosticLevel::Fail,
+                                format!("{name}: initialize returned no result"),
+                            )
+                        }
+                    }
+                    Ok(Err(error)) => (
+                        DiagnosticLevel::Fail,
+                        format!("{name}: spawn/initialize failed: {error}"),
+                    ),
+                    Err(_) => (
+                        DiagnosticLevel::Fail,
+                        format!("{name}: timed out during initialize"),
+                    ),
+                }
+            });
+            detail
+        }
+        other => (
+            DiagnosticLevel::Warn,
+            format!(
+                "{name}: transport {:?} configured (active health probe not implemented)",
+                other.transport()
+            ),
+        ),
+    }
+}
+
+fn check_mcp_server_health(config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
+    let Some(config) = config else {
+        return DiagnosticCheck::new(
+            "MCP server health",
+            DiagnosticLevel::Warn,
+            "runtime config could not be loaded, so MCP servers were not inspected",
+        );
+    };
+    let servers = config.mcp().servers();
+    if servers.is_empty() {
+        return DiagnosticCheck::new(
+            "MCP server health",
+            DiagnosticLevel::Warn,
+            "no MCP servers are configured",
+        );
+    }
+    let results = servers
+        .iter()
+        .map(|(name, server)| check_one_mcp_server(name, server))
+        .collect::<Vec<_>>();
+    let level = if results
+        .iter()
+        .any(|(level, _)| *level == DiagnosticLevel::Fail)
+    {
+        DiagnosticLevel::Fail
+    } else if results
+        .iter()
+        .any(|(level, _)| *level == DiagnosticLevel::Warn)
+    {
+        DiagnosticLevel::Warn
+    } else {
+        DiagnosticLevel::Ok
+    };
+    DiagnosticCheck::new(
+        "MCP server health",
+        level,
+        format!("checked {} configured MCP server(s)", servers.len()),
+    )
+    .with_details(results.into_iter().map(|(_, detail)| detail).collect())
+}
+
+fn check_network_connectivity() -> DiagnosticCheck {
+    let address = match ("api.anthropic.com", 443).to_socket_addrs() {
+        Ok(mut addrs) => match addrs.next() {
+            Some(addr) => addr,
+            None => {
+                return DiagnosticCheck::new(
+                    "Network connectivity",
+                    DiagnosticLevel::Fail,
+                    "DNS resolution returned no addresses for api.anthropic.com",
+                );
+            }
+        },
+        Err(error) => {
+            return DiagnosticCheck::new(
+                "Network connectivity",
+                DiagnosticLevel::Fail,
+                format!("failed to resolve api.anthropic.com: {error}"),
+            );
+        }
+    };
+    match TcpStream::connect_timeout(&address, Duration::from_secs(5)) {
+        Ok(stream) => {
+            let _ = stream.shutdown(std::net::Shutdown::Both);
+            DiagnosticCheck::new(
+                "Network connectivity",
+                DiagnosticLevel::Ok,
+                format!("connected to {address}"),
+            )
+        }
+        Err(error) => DiagnosticCheck::new(
+            "Network connectivity",
+            DiagnosticLevel::Fail,
+            format!("failed to connect to {address}: {error}"),
+        ),
+    }
+}
+
+fn check_system_info(cwd: &Path, config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
+    let mut details = vec![
+        format!("os={} arch={}", env::consts::OS, env::consts::ARCH),
+        format!("cwd={}", cwd.display()),
+        format!("cli_version={VERSION}"),
+        format!("build_target={}", BUILD_TARGET.unwrap_or("<unknown>")),
+        format!("git_sha={}", GIT_SHA.unwrap_or("<unknown>")),
+    ];
+    if let Some(config) = config {
+        details.push(format!(
+            "resolved_model={} loaded_config_files={}",
+            config.model().unwrap_or(DEFAULT_MODEL),
+            config.loaded_entries().len()
+        ));
+    }
+    DiagnosticCheck::new(
+        "System info",
+        DiagnosticLevel::Ok,
+        "captured local runtime and build metadata",
+    )
+    .with_details(details)
+}
+
 fn print_system_prompt(cwd: PathBuf, date: String) {
     match load_system_prompt(cwd, date, env::consts::OS, "unknown") {
         Ok(sections) => println!("{}", sections.join("\n\n")),
@@ -2358,6 +2984,7 @@ fn print_help() {
     println!("  rusty-claude-cli system-prompt [--cwd PATH] [--date YYYY-MM-DD]");
     println!("  rusty-claude-cli login");
     println!("  rusty-claude-cli logout");
+    println!("  rusty-claude-cli doctor");
     println!();
     println!("Flags:");
     println!("  --model MODEL              Override the active model");
@@ -2384,6 +3011,7 @@ fn print_help() {
     println!("  rusty-claude-cli --allowedTools read,glob \"summarize Cargo.toml\"");
     println!("  rusty-claude-cli --resume session.json /status /diff /export notes.txt");
     println!("  rusty-claude-cli login");
+    println!("  rusty-claude-cli doctor");
 }
 
 #[cfg(test)]
@@ -2525,7 +3153,7 @@ mod tests {
     }
 
     #[test]
-    fn parses_login_and_logout_subcommands() {
+    fn parses_login_logout_and_doctor_subcommands() {
         assert_eq!(
             parse_args(&["login".to_string()]).expect("login should parse"),
             CliAction::Login
@@ -2534,6 +3162,10 @@ mod tests {
             parse_args(&["logout".to_string()]).expect("logout should parse"),
             CliAction::Logout
         );
+        assert_eq!(
+            parse_args(&["doctor".to_string()]).expect("doctor should parse"),
+            CliAction::Doctor
+        );
     }
 
     #[test]
@@ -2797,7 +3429,7 @@ mod tests {
     fn status_context_reads_real_workspace_metadata() {
         let context = status_context(None).expect("status context should load");
         assert!(context.cwd.is_absolute());
-        assert!(context.discovered_config_files >= 3);
+        assert_eq!(context.discovered_config_files, 5);
         assert!(context.loaded_config_files <= context.discovered_config_files);
     }
 
@@ -2894,6 +3526,87 @@ mod tests {
         assert!(help.contains("Shift+Enter/Ctrl+J"));
     }
 
+    #[test]
+    fn oauth_status_classifies_missing_and_expired_tokens() {
+        let root = std::env::temp_dir().join(format!(
+            "doctor-oauth-status-{}",
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("time")
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&root).expect("temp dir");
+        std::env::set_var("CLAUDE_CONFIG_HOME", &root);
+
+        assert_eq!(
+            super::classify_oauth_status()
+                .expect("missing should classify")
+                .0,
+            super::OAuthDiagnosticStatus::Missing
+        );
+
+        runtime::save_oauth_credentials(&runtime::OAuthTokenSet {
+            access_token: "token".to_string(),
+            refresh_token: Some("refresh".to_string()),
+            expires_at: Some(1),
+            scopes: vec!["scope:a".to_string()],
+        })
+        .expect("save oauth");
+        assert_eq!(
+            super::classify_oauth_status()
+                .expect("expired should classify")
+                .0,
+            super::OAuthDiagnosticStatus::ExpiredRefreshable
+        );
+
+        runtime::clear_oauth_credentials().expect("clear oauth");
+        std::fs::remove_dir_all(&root).expect("cleanup");
+        std::env::remove_var("CLAUDE_CONFIG_HOME");
+    }
+
+    #[test]
+    fn config_validation_flags_invalid_json() {
+        let root = std::env::temp_dir().join(format!(
+            "doctor-config-{}",
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("time")
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&root).expect("temp dir");
+        let path = root.join("settings.json");
+        std::fs::write(&path, "[]").expect("write invalid top-level");
+        let check = super::validate_config_file(&path);
+        assert!(check.exists);
+        assert!(!check.valid);
+        assert!(check.note.contains("not an object"));
+        std::fs::remove_dir_all(&root).expect("cleanup");
+    }
+
+    #[test]
+    fn doctor_report_renders_requested_sections() {
+        let report = super::DoctorReport {
+            checks: vec![
+                super::DiagnosticCheck::new(
+                    "API key validity",
+                    super::DiagnosticLevel::Ok,
+                    "accepted",
+                ),
+                super::DiagnosticCheck::new(
+                    "System info",
+                    super::DiagnosticLevel::Warn,
+                    "captured",
+                )
+                .with_details(vec!["os=linux".to_string()]),
+            ],
+        };
+        let rendered = report.render();
+        assert!(rendered.contains("Doctor diagnostics"));
+        assert!(rendered.contains("API key validity"));
+        assert!(rendered.contains("System info"));
+        assert!(rendered.contains("Warnings         1"));
+    }
+
     #[test]
     fn tool_rendering_helpers_compact_output() {
         let start = format_tool_call_start("read_file", r#"{"path":"src/main.rs"}"#);

rust/crates/rusty-claude-cli/src/render.rs

@@ -21,7 +21,6 @@ pub struct ColorTheme {
     inline_code: Color,
     link: Color,
     quote: Color,
-    table_border: Color,
     spinner_active: Color,
     spinner_done: Color,
     spinner_failed: Color,
@@ -36,7 +35,6 @@ impl Default for ColorTheme {
             inline_code: Color::Green,
             link: Color::Blue,
             quote: Color::DarkGrey,
-            table_border: Color::DarkCyan,
             spinner_active: Color::Blue,
             spinner_done: Color::Green,
             spinner_failed: Color::Red,
@@ -115,70 +113,24 @@ impl Spinner {
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
-enum ListKind {
-    Unordered,
-    Ordered { next_index: u64 },
-}
-
-#[derive(Debug, Default, Clone, PartialEq, Eq)]
-struct TableState {
-    headers: Vec<String>,
-    rows: Vec<Vec<String>>,
-    current_row: Vec<String>,
-    current_cell: String,
-    in_head: bool,
-}
-
-impl TableState {
-    fn push_cell(&mut self) {
-        let cell = self.current_cell.trim().to_string();
-        self.current_row.push(cell);
-        self.current_cell.clear();
-    }
-
-    fn finish_row(&mut self) {
-        if self.current_row.is_empty() {
-            return;
-        }
-        let row = std::mem::take(&mut self.current_row);
-        if self.in_head {
-            self.headers = row;
-        } else {
-            self.rows.push(row);
-        }
-    }
-}
-
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 struct RenderState {
     emphasis: usize,
     strong: usize,
     quote: usize,
-    list_stack: Vec<ListKind>,
-    table: Option<TableState>,
+    list: usize,
 }
 
 impl RenderState {
     fn style_text(&self, text: &str, theme: &ColorTheme) -> String {
-        let mut styled = text.to_string();
         if self.strong > 0 {
-            styled = format!("{}", styled.bold().with(theme.strong));
-        }
-        if self.emphasis > 0 {
-            styled = format!("{}", styled.italic().with(theme.emphasis));
-        }
-        if self.quote > 0 {
-            styled = format!("{}", styled.with(theme.quote));
-        }
-        styled
-    }
-
-    fn capture_target_mut<'a>(&'a mut self, output: &'a mut String) -> &'a mut String {
-        if let Some(table) = self.table.as_mut() {
-            &mut table.current_cell
+            format!("{}", text.bold().with(theme.strong))
+        } else if self.emphasis > 0 {
+            format!("{}", text.italic().with(theme.emphasis))
+        } else if self.quote > 0 {
+            format!("{}", text.with(theme.quote))
         } else {
-            output
+            text.to_string()
         }
     }
 }
@@ -238,7 +190,6 @@ impl TerminalRenderer {
         output.trim_end().to_string()
     }
 
-    #[allow(clippy::too_many_lines)]
     fn render_event(
         &self,
         event: Event<'_>,
@@ -252,22 +203,12 @@ impl TerminalRenderer {
             Event::Start(Tag::Heading { level, .. }) => self.start_heading(level as u8, output),
             Event::End(TagEnd::Heading(..) | TagEnd::Paragraph) => output.push_str("\n\n"),
             Event::Start(Tag::BlockQuote(..)) => self.start_quote(state, output),
-            Event::End(TagEnd::BlockQuote(..)) => {
-                state.quote = state.quote.saturating_sub(1);
-                output.push('\n');
-            }
-            Event::End(TagEnd::Item) | Event::SoftBreak | Event::HardBreak => {
-                state.capture_target_mut(output).push('\n');
-            }
-            Event::Start(Tag::List(first_item)) => {
-                let kind = match first_item {
-                    Some(index) => ListKind::Ordered { next_index: index },
-                    None => ListKind::Unordered,
-                };
-                state.list_stack.push(kind);
-            }
+            Event::End(TagEnd::BlockQuote(..) | TagEnd::Item)
+            | Event::SoftBreak
+            | Event::HardBreak => output.push('\n'),
+            Event::Start(Tag::List(_)) => state.list += 1,
             Event::End(TagEnd::List(..)) => {
-                state.list_stack.pop();
+                state.list = state.list.saturating_sub(1);
                 output.push('\n');
             }
             Event::Start(Tag::Item) => Self::start_item(state, output),
@@ -291,85 +232,57 @@ impl TerminalRenderer {
             Event::Start(Tag::Strong) => state.strong += 1,
             Event::End(TagEnd::Strong) => state.strong = state.strong.saturating_sub(1),
             Event::Code(code) => {
-                let rendered =
-                    format!("{}", format!("`{code}`").with(self.color_theme.inline_code));
-                state.capture_target_mut(output).push_str(&rendered);
+                let _ = write!(
+                    output,
+                    "{}",
+                    format!("`{code}`").with(self.color_theme.inline_code)
+                );
             }
             Event::Rule => output.push_str("---\n"),
             Event::Text(text) => {
                 self.push_text(text.as_ref(), state, output, code_buffer, *in_code_block);
             }
-            Event::Html(html) | Event::InlineHtml(html) => {
-                state.capture_target_mut(output).push_str(&html);
-            }
+            Event::Html(html) | Event::InlineHtml(html) => output.push_str(&html),
             Event::FootnoteReference(reference) => {
-                let _ = write!(state.capture_target_mut(output), "[{reference}]");
-            }
-            Event::TaskListMarker(done) => {
-                state
-                    .capture_target_mut(output)
-                    .push_str(if done { "[x] " } else { "[ ] " });
-            }
-            Event::InlineMath(math) | Event::DisplayMath(math) => {
-                state.capture_target_mut(output).push_str(&math);
+                let _ = write!(output, "[{reference}]");
             }
+            Event::TaskListMarker(done) => output.push_str(if done { "[x] " } else { "[ ] " }),
+            Event::InlineMath(math) | Event::DisplayMath(math) => output.push_str(&math),
             Event::Start(Tag::Link { dest_url, .. }) => {
-                let rendered = format!(
+                let _ = write!(
+                    output,
                     "{}",
                     format!("[{dest_url}]")
                         .underlined()
                         .with(self.color_theme.link)
                 );
-                state.capture_target_mut(output).push_str(&rendered);
             }
             Event::Start(Tag::Image { dest_url, .. }) => {
-                let rendered = format!(
+                let _ = write!(
+                    output,
                     "{}",
                     format!("[image:{dest_url}]").with(self.color_theme.link)
                 );
-                state.capture_target_mut(output).push_str(&rendered);
             }
-            Event::Start(Tag::Table(..)) => state.table = Some(TableState::default()),
-            Event::End(TagEnd::Table) => {
-                if let Some(table) = state.table.take() {
-                    output.push_str(&self.render_table(&table));
-                    output.push_str("\n\n");
-                }
-            }
-            Event::Start(Tag::TableHead) => {
-                if let Some(table) = state.table.as_mut() {
-                    table.in_head = true;
-                }
-            }
-            Event::End(TagEnd::TableHead) => {
-                if let Some(table) = state.table.as_mut() {
-                    table.finish_row();
-                    table.in_head = false;
-                }
-            }
-            Event::Start(Tag::TableRow) => {
-                if let Some(table) = state.table.as_mut() {
-                    table.current_row.clear();
-                    table.current_cell.clear();
-                }
-            }
-            Event::End(TagEnd::TableRow) => {
-                if let Some(table) = state.table.as_mut() {
-                    table.finish_row();
-                }
-            }
-            Event::Start(Tag::TableCell) => {
-                if let Some(table) = state.table.as_mut() {
-                    table.current_cell.clear();
-                }
-            }
-            Event::End(TagEnd::TableCell) => {
-                if let Some(table) = state.table.as_mut() {
-                    table.push_cell();
-                }
-            }
-            Event::Start(Tag::Paragraph | Tag::MetadataBlock(..) | _)
-            | Event::End(TagEnd::Link | TagEnd::Image | TagEnd::MetadataBlock(..) | _) => {}
+            Event::Start(
+                Tag::Paragraph
+                | Tag::Table(..)
+                | Tag::TableHead
+                | Tag::TableRow
+                | Tag::TableCell
+                | Tag::MetadataBlock(..)
+                | _,
+            )
+            | Event::End(
+                TagEnd::Link
+                | TagEnd::Image
+                | TagEnd::Table
+                | TagEnd::TableHead
+                | TagEnd::TableRow
+                | TagEnd::TableCell
+                | TagEnd::MetadataBlock(..)
+                | _,
+            ) => {}
         }
     }
 
@@ -389,19 +302,9 @@ impl TerminalRenderer {
         let _ = write!(output, "{}", "│ ".with(self.color_theme.quote));
     }
 
-    fn start_item(state: &mut RenderState, output: &mut String) {
-        let depth = state.list_stack.len().saturating_sub(1);
-        output.push_str(&"  ".repeat(depth));
-
-        let marker = match state.list_stack.last_mut() {
-            Some(ListKind::Ordered { next_index }) => {
-                let value = *next_index;
-                *next_index += 1;
-                format!("{value}. ")
-            }
-            _ => "• ".to_string(),
-        };
-        output.push_str(&marker);
+    fn start_item(state: &RenderState, output: &mut String) {
+        output.push_str(&"  ".repeat(state.list.saturating_sub(1)));
+        output.push_str("• ");
     }
 
     fn start_code_block(&self, code_language: &str, output: &mut String) {
@@ -425,7 +328,7 @@ impl TerminalRenderer {
     fn push_text(
         &self,
         text: &str,
-        state: &mut RenderState,
+        state: &RenderState,
         output: &mut String,
         code_buffer: &mut String,
         in_code_block: bool,
@@ -433,82 +336,10 @@ impl TerminalRenderer {
         if in_code_block {
             code_buffer.push_str(text);
         } else {
-            let rendered = state.style_text(text, &self.color_theme);
-            state.capture_target_mut(output).push_str(&rendered);
+            output.push_str(&state.style_text(text, &self.color_theme));
         }
     }
 
-    fn render_table(&self, table: &TableState) -> String {
-        let mut rows = Vec::new();
-        if !table.headers.is_empty() {
-            rows.push(table.headers.clone());
-        }
-        rows.extend(table.rows.iter().cloned());
-
-        if rows.is_empty() {
-            return String::new();
-        }
-
-        let column_count = rows.iter().map(Vec::len).max().unwrap_or(0);
-        let widths = (0..column_count)
-            .map(|column| {
-                rows.iter()
-                    .filter_map(|row| row.get(column))
-                    .map(|cell| visible_width(cell))
-                    .max()
-                    .unwrap_or(0)
-            })
-            .collect::<Vec<_>>();
-
-        let border = format!("{}", "│".with(self.color_theme.table_border));
-        let separator = widths
-            .iter()
-            .map(|width| "─".repeat(*width + 2))
-            .collect::<Vec<_>>()
-            .join(&format!("{}", "┼".with(self.color_theme.table_border)));
-        let separator = format!("{border}{separator}{border}");
-
-        let mut output = String::new();
-        if !table.headers.is_empty() {
-            output.push_str(&self.render_table_row(&table.headers, &widths, true));
-            output.push('\n');
-            output.push_str(&separator);
-            if !table.rows.is_empty() {
-                output.push('\n');
-            }
-        }
-
-        for (index, row) in table.rows.iter().enumerate() {
-            output.push_str(&self.render_table_row(row, &widths, false));
-            if index + 1 < table.rows.len() {
-                output.push('\n');
-            }
-        }
-
-        output
-    }
-
-    fn render_table_row(&self, row: &[String], widths: &[usize], is_header: bool) -> String {
-        let border = format!("{}", "│".with(self.color_theme.table_border));
-        let mut line = String::new();
-        line.push_str(&border);
-
-        for (index, width) in widths.iter().enumerate() {
-            let cell = row.get(index).map_or("", String::as_str);
-            line.push(' ');
-            if is_header {
-                let _ = write!(line, "{}", cell.bold().with(self.color_theme.heading));
-            } else {
-                line.push_str(cell);
-            }
-            let padding = width.saturating_sub(visible_width(cell));
-            line.push_str(&" ".repeat(padding + 1));
-            line.push_str(&border);
-        }
-
-        line
-    }
-
     #[must_use]
     pub fn highlight_code(&self, code: &str, language: &str) -> String {
         let syntax = self
@@ -541,11 +372,11 @@ impl TerminalRenderer {
     }
 }
 
-fn visible_width(input: &str) -> usize {
-    strip_ansi(input).chars().count()
-}
+#[cfg(test)]
+mod tests {
+    use super::{Spinner, TerminalRenderer};
 
-fn strip_ansi(input: &str) -> String {
+    fn strip_ansi(input: &str) -> String {
         let mut output = String::new();
         let mut chars = input.chars().peekable();
 
@@ -565,11 +396,7 @@ fn strip_ansi(input: &str) -> String {
         }
 
         output
-}
-
-#[cfg(test)]
-mod tests {
-    use super::{strip_ansi, Spinner, TerminalRenderer};
+    }
 
     #[test]
     fn renders_markdown_with_styling_and_lists() {
@@ -595,34 +422,6 @@ mod tests {
         assert!(markdown_output.contains('\u{1b}'));
     }
 
-    #[test]
-    fn renders_ordered_and_nested_lists() {
-        let terminal_renderer = TerminalRenderer::new();
-        let markdown_output =
-            terminal_renderer.render_markdown("1. first\n2. second\n   - nested\n   - child");
-        let plain_text = strip_ansi(&markdown_output);
-
-        assert!(plain_text.contains("1. first"));
-        assert!(plain_text.contains("2. second"));
-        assert!(plain_text.contains("  • nested"));
-        assert!(plain_text.contains("  • child"));
-    }
-
-    #[test]
-    fn renders_tables_with_alignment() {
-        let terminal_renderer = TerminalRenderer::new();
-        let markdown_output = terminal_renderer
-            .render_markdown("| Name | Value |\n| ---- | ----- |\n| alpha | 1 |\n| beta | 22 |");
-        let plain_text = strip_ansi(&markdown_output);
-        let lines = plain_text.lines().collect::<Vec<_>>();
-
-        assert_eq!(lines[0], "│ Name  │ Value │");
-        assert_eq!(lines[1], "│───────┼───────│");
-        assert_eq!(lines[2], "│ alpha │ 1     │");
-        assert_eq!(lines[3], "│ beta  │ 22    │");
-        assert!(markdown_output.contains('\u{1b}'));
-    }
-
     #[test]
     fn spinner_advances_frames() {
         let terminal_renderer = TerminalRenderer::new();