fix: make server-not-running guidance session-aware

refs #1941

Author: season179

src/cli/server_not_running.rs

@@ -26,18 +26,32 @@ impl std::error::Error for ServerNotRunningReported {}
 /// Builds the friendly `server_not_running` ErrorResponse shown when no
 /// server is listening on the resolved API socket.
 pub(super) fn response(request_id: &str, socket_path: &Path) -> ErrorResponse {
+    let attach_command = startup_command(socket_path);
     ErrorResponse {
         id: request_id.to_string(),
         error: ErrorBody {
             code: "server_not_running".into(),
             message: format!(
-                "no herdr server is running at {}; run `herdr` to start one",
+                "no herdr server is running at {}; run `{attach_command}` to start or attach it",
                 socket_path.display()
             ),
         },
     }
 }
 
+fn startup_command(socket_path: &Path) -> String {
+    let session_socket =
+        crate::session::api_socket_path_for(crate::session::active_name().as_deref());
+    if socket_path == session_socket {
+        crate::session::local_attach_command()
+    } else {
+        // A socket override wins over an inherited HERDR_SESSION. Keep the
+        // command in the current environment so it starts the overridden
+        // target instead of directing the user to an unrelated session.
+        "herdr".to_string()
+    }
+}
+
 /// Wraps the response in the recognizable marker WITHOUT printing. The caller
 /// that ultimately surfaces the error prints the carried response (see
 /// `reported_response`); recovering callers simply drop it.

tests/cli/sessions.rs

@@ -184,6 +184,69 @@ fn named_sessions_use_separate_servers_and_workspace_state() {
     cleanup_test_base(&base);
 }
 
+#[test]
+fn dead_server_cli_reports_one_session_aware_json_line() {
+    fn assert_server_not_running(
+        output: std::process::Output,
+        socket_path: &Path,
+        attach_command: &str,
+    ) {
+        assert_eq!(
+            output.status.code(),
+            Some(1),
+            "stdout={} stderr={}",
+            String::from_utf8_lossy(&output.stdout),
+            String::from_utf8_lossy(&output.stderr)
+        );
+        assert!(output.stdout.is_empty(), "server errors belong on stderr");
+
+        let stderr = String::from_utf8(output.stderr).unwrap();
+        let lines: Vec<_> = stderr.lines().collect();
+        assert_eq!(lines.len(), 1, "expected exactly one JSON line: {stderr:?}");
+
+        let response: serde_json::Value = serde_json::from_str(lines[0]).unwrap();
+        assert_eq!(response["id"], "cli:workspace:create");
+        assert_eq!(response["error"]["code"], "server_not_running");
+        assert_eq!(
+            response["error"]["message"],
+            format!(
+                "no herdr server is running at {}; run `{attach_command}` to start or attach it",
+                socket_path.display()
+            )
+        );
+    }
+
+    let base = unique_test_dir();
+    let config_home = base.join("config");
+    let runtime_dir = base.join("runtime");
+    fs::create_dir_all(&runtime_dir).unwrap();
+    register_runtime_dir(&runtime_dir);
+
+    let named_socket = named_session_socket(&config_home, "foo");
+    let missing = run_named_cli(
+        &config_home,
+        &runtime_dir,
+        &["--session", "foo", "workspace", "create"],
+    );
+    assert_server_not_running(missing, &named_socket, "herdr session attach foo");
+
+    let stale_socket = runtime_dir.join("stale.sock");
+    drop(UnixListener::bind(&stale_socket).unwrap());
+    let stale = Command::new(env!("CARGO_BIN_EXE_herdr"))
+        .args(["workspace", "create"])
+        .env("XDG_CONFIG_HOME", &config_home)
+        .env("XDG_RUNTIME_DIR", &runtime_dir)
+        .env("HERDR_SOCKET_PATH", &stale_socket)
+        .env("HERDR_SESSION", "unrelated")
+        .env_remove("HERDR_CLIENT_SOCKET_PATH")
+        .env_remove("HERDR_ENV")
+        .output()
+        .unwrap();
+    assert_server_not_running(stale, &stale_socket, "herdr");
+
+    cleanup_test_base(&base);
+}
+
 #[test]
 fn integration_commands_run_locally_when_server_is_missing() {
     let base = unique_test_dir();