[Bug]: Sandbox probe fails with localhost health connection refused even when Docker doctor is healthy

[benjaminshafii]

User report

A user report diagnostic bundle shows sandbox probe failure despite Docker preflight success.

Repro evidence (sanitized)

• App: v0.11.134 (d1658182f0ca)
• Orchestrator: 0.11.133
• OpenWork server: 0.11.132
• sandbox_doctor: ready=true
  • docker --version status 0
  • docker info status 0
• Probe duration: ~90s (startedAt -> finishedAt)
• Final error:
  • Sandbox probe failed to start: http://127.0.0.1:<port>/health: Connection refused (os error 61)

Why this matters

This is a distinct failure mode from Docker-preflight-not-ready. The system passes Docker checks but fails to bring up or reach the probe health endpoint.

Expected behavior

If Docker doctor is healthy, sandbox probe should either:

• reach healthy endpoint within bounded time, or
• fail fast with clear stage-level diagnostics indicating whether process start, bind, or readiness failed.

Suggested investigation

1. Add structured stage logs around detached orchestrator startup (spawned pid, selected host/port, first bind success, first health attempt).
2. Verify health endpoint bind/address assumptions (127.0.0.1 vs host mode/network namespace edge cases).
3. Ensure probe timeout path emits final reason with last known orchestrator stderr/stdout snippet.
4. Check version skew effects (app 0.11.134 + orchestrator 0.11.133 + server 0.11.132) on probe contract.

Acceptance criteria

• Repro scenario no longer ends in opaque connection refused after successful doctor.
• Failure output includes deterministic stage and actionable remediation.
• Probe reliability validated on macOS with OrbStack/Docker Desktop variants.

[caoergou]

Analysis

I've analyzed the sandbox probe code in packages/desktop/src-tauri/src/commands/orchestrator.rs. The current error handling provides limited diagnostic information when health check fails.

Current Behavior

When sandbox_doctor() passes but health check fails (line 883-885):

Err(err) => {
    last_error = Some(err.to_string());  // Only simple error string
}

On timeout (line 908-910):

let message = last_error.unwrap_or_else(|| "Timed out waiting for OpenWork server".to_string());
// No distinction between error types, no container logs

Proposed Improvement

1. Enrich error messages with context:

Err(err) => {
    let error_type = if err.to_string().contains("connection refused") {
        "ConnectionRefused"
    } else if err.to_string().contains("timed out") {
        "Timeout"
    } else {
        "Unknown"
    };
    last_error = Some(format!(
        "[{}] {} (url: {}, containerState: {:?})",
        error_type,
        err,
        openwork_url,
        last_container_state
    ));
}

2. Add troubleshooting hints on timeout:

if start.elapsed() >= Duration::from_millis(health_timeout_ms) {
    let troubleshooting = match last_container_state.as_deref() {
        Some("running") => "Container is running but health check failed. Check container logs with: docker logs <container_name>",
        Some("exited") => "Container exited unexpectedly. Check container logs for crash details.",
        None => "Container not found. Docker may have failed to create it.",
        _ => "Unknown container state."
    };
    // Include troubleshooting in the error message
}

3. Include container state in all progress events (already partially done in emit_sandbox_progress).

Benefits

• Users get actionable hints instead of opaque errors
• Easier to diagnose if the issue reoccurs
• Helps distinguish between Docker startup issues vs network binding issues

Would this approach be acceptable? I'm happy to submit a PR with these improvements if this aligns with the direction you're thinking.