Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Assistant: say when an installed agent can't start, and how to reinstall it (#9034) (#9655)

PaddleStroked61ec6048019
diff --git a/assets/locales/pending/agent-chat-cannot-start.json b/assets/locales/pending/agent-chat-cannot-start.json
new file mode 100644
index 0000000000..933a7a1f9c
--- /dev/null
+++ b/assets/locales/pending/agent-chat-cannot-start.json
@@ -0,0 +1,38 @@
+{
+ "en": {
+ "ui.agent_chat_cannot_start": "Installed, but it does not start: {error}",
+ "ui.agent_chat_reinstall": "{agent} is installed ({program}), but it did not start when SolidCraft checked it: {error}\nIts installation may be incomplete, or made for another kind of computer. Install it again with `{install}`, check that it prints its version in a terminal, then press Refresh."
+ },
+ "ar": {
+ "ui.agent_chat_cannot_start": "مثبّت، لكنه لا يبدأ: {error}",
+ "ui.agent_chat_reinstall": "{agent} مثبّت ({program})، لكنه لم يبدأ عندما فحصه SolidCraft: {error}\nقد يكون تثبيته غير مكتمل، أو مُعدًّا لنوع آخر من الحواسيب. ثبّته من جديد بالأمر `{install}`، وتحقّق من أنه يعرض رقم إصداره في الطرفية، ثم اضغط تحديث."
+ },
+ "de": {
+ "ui.agent_chat_cannot_start": "Installiert, startet aber nicht: {error}",
+ "ui.agent_chat_reinstall": "{agent} ist installiert ({program}), ist aber beim Prüfen durch SolidCraft nicht gestartet: {error}\nDie Installation ist vielleicht unvollständig oder für einen anderen Computertyp. Installieren Sie es erneut mit `{install}`, prüfen Sie, dass es im Terminal seine Version ausgibt, und klicken Sie dann auf Aktualisieren."
+ },
+ "fr": {
+ "ui.agent_chat_cannot_start": "Installé, mais ne démarre pas : {error}",
+ "ui.agent_chat_reinstall": "{agent} est installé ({program}), mais n'a pas démarré quand SolidCraft l'a vérifié : {error}\nSon installation est peut-être incomplète, ou prévue pour un autre type d'ordinateur. Réinstallez-le avec `{install}`, vérifiez qu'il affiche sa version dans un terminal, puis cliquez sur Actualiser."
+ },
+ "he": {
+ "ui.agent_chat_cannot_start": "מותקן, אך אינו מופעל: {error}",
+ "ui.agent_chat_reinstall": "{agent} מותקן ({program}), אך לא הופעל כאשר SolidCraft בדק אותו: {error}\nייתכן שההתקנה שלו חלקית, או שהיא מיועדת לסוג אחר של מחשב. יש להתקין אותו מחדש עם `{install}`, לוודא שהוא מציג את הגרסה שלו במסוף, ואז ללחוץ על רענון."
+ },
+ "ja": {
+ "ui.agent_chat_cannot_start": "インストールされていますが、起動しません: {error}",
+ "ui.agent_chat_reinstall": "{agent} はインストールされています ({program}) が、SolidCraft が確認したときに起動しませんでした: {error}\nインストールが不完全か、別の種類のコンピューター用の可能性があります。`{install}` で再インストールし、ターミナルでバージョンが表示されることを確認してから、再検索を押してください。"
+ },
+ "ko": {
+ "ui.agent_chat_cannot_start": "설치되어 있지만 시작되지 않습니다: {error}",
+ "ui.agent_chat_reinstall": "{agent}이(가) 설치되어 있지만({program}) SolidCraft가 확인할 때 시작되지 않았습니다: {error}\n설치가 완료되지 않았거나 다른 종류의 컴퓨터용일 수 있습니다. `{install}`(으)로 다시 설치하고, 터미널에서 버전이 출력되는지 확인한 뒤 새로 고침을 누르세요."
+ },
+ "vi": {
+ "ui.agent_chat_cannot_start": "Đã cài đặt nhưng không khởi động được: {error}",
+ "ui.agent_chat_reinstall": "{agent} đã được cài đặt ({program}) nhưng không khởi động khi SolidCraft kiểm tra: {error}\nBản cài đặt có thể chưa hoàn tất, hoặc dành cho loại máy tính khác. Hãy cài lại bằng `{install}`, kiểm tra rằng nó in ra phiên bản trong terminal, rồi nhấn Làm mới."
+ },
+ "zh": {
+ "ui.agent_chat_cannot_start": "已安装,但无法启动:{error}",
+ "ui.agent_chat_reinstall": "{agent} 已安装({program}),但 SolidCraft 检查时它没有启动:{error}\n它的安装可能不完整,或是为另一种计算机准备的。请用 `{install}` 重新安装,确认它能在终端中显示版本号,然后点击刷新。"
+ }
+}
diff --git a/crates/ui-egui/src/agent_chat/agents.rs b/crates/ui-egui/src/agent_chat/agents.rs
index c05102b8df..f5ad5e0d72 100644
--- a/crates/ui-egui/src/agent_chat/agents.rs
+++ b/crates/ui-egui/src/agent_chat/agents.rs
@@ -167,6 +167,10 @@ pub struct Entry {
pub key: bool,
/// API: seconds one model request may take (in range).
pub request_timeout_s: u64,
+ /// Found installed, but its program didn't start when asked its version: why (#9034).
+ pub problem: Option<String>,
+ /// Found installed: the command that installs it again.
+ pub install: &'static str,
}
impl Entry {
@@ -183,18 +187,31 @@ impl Entry {
model: c.model.clone(),
key: c.key,
request_timeout_s: c.request_timeout_s.clamp(MIN_REQUEST_TIMEOUT_S, MAX_REQUEST_TIMEOUT_S),
+ problem: None,
+ install: "",
}
}
- /// A short line under the name: the version, the model, or the command.
+ /// A short line under the name: the version, the model, the command, or why it can't start.
pub fn detail(&self) -> String {
match self.kind {
Kind::Api | Kind::Anthropic => format!("{} · {}", self.model, self.base_url),
- Kind::Acp => match &self.version {
- Some(v) => v.clone(),
- None => super::panel::short_command(&self.argv.join(" ")),
+ Kind::Acp => match (&self.problem, &self.version) {
+ (Some(p), _) => crate::i18n::format("ui.agent_chat_cannot_start", &[("error", p)]),
+ (None, Some(v)) => v.clone(),
+ (None, None) => super::panel::short_command(&self.argv.join(" ")),
},
}
}
+ /// What to tell someone starting an agent that was found but didn't start (#9034): the reason,
+ /// and how to install it again. `None` when nothing was seen wrong.
+ pub fn problem_hint(&self) -> Option<String> {
+ let problem = self.problem.as_deref()?;
+ let program = self.argv.first().map(String::as_str).unwrap_or_default();
+ Some(crate::i18n::format(
+ "ui.agent_chat_reinstall",
+ &[("agent", &self.name), ("program", program), ("error", problem), ("install", self.install)],
+ ))
+ }
}
/// Every agent the chat can use: the installed ones found, then the ones the user added.
@@ -214,6 +231,8 @@ pub fn entries(app: &crate::SolveApp) -> Vec<Entry> {
model: String::new(),
key: false,
request_timeout_s: DEFAULT_REQUEST_TIMEOUT_S,
+ problem: f.problem.clone(),
+ install: f.install,
}));
}
out.extend(app.preferences.agents.iter().map(Entry::from_config));
diff --git a/crates/ui-egui/src/agent_chat/discover.rs b/crates/ui-egui/src/agent_chat/discover.rs
index ace05c3c29..24792f42c5 100644
--- a/crates/ui-egui/src/agent_chat/discover.rs
+++ b/crates/ui-egui/src/agent_chat/discover.rs
@@ -187,6 +187,11 @@ pub struct Found {
pub argv: Vec<String>,
pub version: Option<String>,
pub login: Login,
+ /// Why its program doesn't start (#9034): asked for `--version`, it failed without printing
+ /// one, as the `opencode.exe` of an npm install whose setup script didn't run does on Windows.
+ pub problem: Option<String>,
+ /// Its one-line install hint, to reinstall it with.
+ pub install: &'static str,
}
#[derive(Clone, Debug, Default)]
@@ -288,8 +293,24 @@ pub(super) fn command_for(program: &Path) -> Command {
cmd
}
-/// `program --version`'s first line, or `None` after `limit` (the probe is then stopped).
-fn version(program: &Path, limit: Duration) -> Option<String> {
+/// What `program --version` showed.
+#[derive(Debug, Default, PartialEq)]
+struct Probe {
+ /// Its version number, from the first line it printed.
+ version: Option<String>,
+ /// Why it can't start: the system refused to start it, or it failed and printed nothing but
+ /// an error. A probe that runs out of time says nothing either way (a slow machine).
+ problem: Option<String>,
+}
+
+/// How long an agent is given to answer `--version`.
+const PROBE_LIMIT: Duration = Duration::from_secs(3);
+
+/// The longest reason kept from a failed probe.
+const PROBLEM_CHARS: usize = 300;
+
+/// Ask `program --version`; it is stopped after `limit`.
+fn probe(program: &Path, limit: Duration) -> Probe {
let mut cmd = command_for(program);
#[cfg(windows)]
{
@@ -297,23 +318,50 @@ fn version(program: &Path, limit: Duration) -> Option<String> {
// CREATE_NO_WINDOW: probing a console agent doesn't flash a terminal window.
cmd.creation_flags(0x0800_0000);
}
- let mut child = cmd.arg("--version").stdin(Stdio::null()).stdout(Stdio::piped()).stderr(Stdio::null()).spawn().ok()?;
+ let mut child = match cmd.arg("--version").stdin(Stdio::null()).stdout(Stdio::piped()).stderr(Stdio::piped()).spawn() {
+ Ok(child) => child,
+ // Windows: "not a valid Win32 application" (193), "not compatible with the version of
+ // Windows you're running" (216); elsewhere: not allowed to run it, an unknown format.
+ // Windows leaves the program's place in its message as `%1`.
+ Err(e) => return Probe { version: None, problem: Some(cut(&e.to_string().replace("%1", &program.display().to_string()))) },
+ };
let start = Instant::now();
- loop {
+ let status = loop {
match child.try_wait() {
- Ok(Some(_)) => break,
+ Ok(Some(status)) => break status,
Ok(None) if start.elapsed() < limit => std::thread::sleep(Duration::from_millis(20)),
_ => {
let _ = child.kill();
let _ = child.wait();
- return None;
+ return Probe::default();
}
}
+ };
+ let out = read_capped(child.stdout.take());
+ if let Some(line) = out.lines().map(str::trim).find(|l| !l.is_empty()) {
+ return Probe { version: Some(version_of(line)), problem: None };
+ }
+ if status.success() {
+ return Probe::default();
+ }
+ // Through a `.cmd` shim, Windows' own refusal arrives on stderr with a failing exit code.
+ let err = read_capped(child.stderr.take());
+ let reason = err.lines().map(str::trim).find(|l| !l.is_empty()).map(str::to_string).unwrap_or_else(|| status.to_string());
+ Probe { version: None, problem: Some(cut(&reason)) }
+}
+
+/// What a finished probe wrote on a pipe, up to 64 KiB.
+fn read_capped(pipe: Option<impl std::io::Read>) -> String {
+ let mut bytes = Vec::new();
+ if let Some(p) = pipe {
+ let _ = std::io::Read::read_to_end(&mut p.take(64 * 1024), &mut bytes);
}
- let mut out = String::new();
- std::io::Read::read_to_string(&mut child.stdout.take()?, &mut out).ok()?;
- let line = out.lines().map(str::trim).find(|l| !l.is_empty())?;
- Some(version_of(line))
+ String::from_utf8_lossy(&bytes).into_owned()
+}
+
+/// `text`, cut short.
+fn cut(text: &str) -> String {
+ text.chars().take(PROBLEM_CHARS).collect()
}
/// The version number in a `--version` line (`codex-cli 0.162.1`, `2.1.295 (Claude Code)`,
@@ -342,10 +390,10 @@ fn login_of(k: &Known, home: Option<&Path>) -> Login {
/// Look for every known agent. Blocking (each probe has a time limit): run it off the UI thread.
pub fn detect() -> Detection {
- detect_in(&search_dirs(), home().as_deref())
+ detect_in(&search_dirs(), home().as_deref(), PROBE_LIMIT)
}
-fn detect_in(dirs: &[PathBuf], home: Option<&Path>) -> Detection {
+fn detect_in(dirs: &[PathBuf], home: Option<&Path>, limit: Duration) -> Detection {
let t0 = Instant::now();
let mut d = Detection::default();
for k in KNOWN {
@@ -358,8 +406,8 @@ fn detect_in(dirs: &[PathBuf], home: Option<&Path>) -> Detection {
let login = login_of(k, home);
let mut argv = vec![path.to_string_lossy().into_owned()];
argv.extend(k.args.iter().map(|a| a.to_string()));
- let version = if k.reports_version { version(&path, Duration::from_secs(3)) } else { None };
- d.found.push(Found { id: k.id, name: k.name, version, argv, login });
+ let Probe { version, problem } = if k.reports_version { probe(&path, limit) } else { Probe::default() };
+ d.found.push(Found { id: k.id, name: k.name, version, argv, login, problem, install: k.install });
}
d.took_ms = u64::try_from(t0.elapsed().as_millis()).unwrap_or(u64::MAX);
d
@@ -544,7 +592,7 @@ mod tests {
};
let ids = |d: &Detection| (d.found.iter().map(|f| f.id).collect::<Vec<_>>(), d.missing.iter().map(|m| m.id).collect::<Vec<_>>());
- let none = detect_in(std::slice::from_ref(&root), None);
+ let none = detect_in(std::slice::from_ref(&root), None, PROBE_LIMIT);
let (found, missing) = ids(&none);
assert!(found.is_empty());
assert!(missing.contains(&"antigravity") && !missing.contains(&"gemini"), "{missing:?}");
@@ -554,7 +602,7 @@ mod tests {
run("gemini", "echo gemini 0.64.0");
// A server that would take seconds to answer `--version`, which Antigravity is never asked.
run("agy_acp_server.par", "sleep 30");
- let both = detect_in(std::slice::from_ref(&root), None);
+ let both = detect_in(std::slice::from_ref(&root), None, PROBE_LIMIT);
let (found, missing) = ids(&both);
assert_eq!(found, ["antigravity", "gemini"]);
assert!(!missing.contains(&"antigravity") && !missing.contains(&"gemini"), "{missing:?}");
@@ -573,6 +621,73 @@ mod tests {
assert_eq!(KNOWN.first().map(|k| k.id), Some("claude"), "the Claude Code adapter is the default");
}
+ /// #9034: npm installed OpenCode without running its setup script, so the `opencode.exe` its
+ /// `.cmd` shim starts is one Windows refuses. It is still found (its shim is there), with
+ /// the system's reason and the command to install it again, while an agent that answers
+ /// `--version`, or ends without a word but successfully, has no problem.
+ #[test]
+ fn an_agent_that_does_not_start_is_found_with_the_reason() {
+ let root = std::env::temp_dir().join(format!("sc-agent-broken-{}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&root);
+ std::fs::create_dir_all(&root).unwrap();
+ #[cfg(windows)]
+ {
+ // npm's layout: the shim in the prefix, the program under node_modules.
+ let bin = root.join("node_modules").join("opencode-ai").join("bin");
+ std::fs::create_dir_all(&bin).unwrap();
+ std::fs::write(bin.join("opencode.exe"), "not a program for this computer").unwrap();
+ std::fs::write(root.join("opencode.cmd"), "@ECHO off\r\n\"%~dp0\\node_modules\\opencode-ai\\bin\\opencode.exe\" %*\r\n").unwrap();
+ // Started directly, the system itself refuses it.
+ std::fs::write(root.join("copilot.exe"), "not a program either").unwrap();
+ std::fs::write(root.join("grok.cmd"), "@echo off\r\nexit /b 3\r\n").unwrap();
+ std::fs::write(root.join("qwen.cmd"), "@echo off\r\necho 0.1.2\r\n").unwrap();
+ std::fs::write(root.join("goose.cmd"), "@echo off\r\n").unwrap();
+ }
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ let run = |name: &str, body: &str| {
+ let path = root.join(name);
+ std::fs::write(&path, format!("#!/bin/sh\n{body}\n")).unwrap();
+ std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();
+ };
+ run("opencode", "echo 'cannot execute binary file: Exec format error' >&2; exit 126");
+ // Not allowed to run: the system refuses it.
+ std::fs::write(root.join("copilot"), "not a program").unwrap();
+ std::fs::set_permissions(root.join("copilot"), std::fs::Permissions::from_mode(0o644)).unwrap();
+ run("grok", "exit 3");
+ run("qwen", "echo 0.1.2");
+ run("goose", "true");
+ }
+ // A generous limit: on a loaded machine `cmd` alone can take longer than three seconds to
+ // start, and a probe that runs out of time reports nothing.
+ let d = detect_in(std::slice::from_ref(&root), None, Duration::from_secs(60));
+ let found = |id: &str| d.found.iter().find(|f| f.id == id).unwrap_or_else(|| panic!("{id} not found: {:?}", d.found));
+
+ let opencode = found("opencode");
+ assert_eq!(opencode.version, None);
+ assert!(opencode.problem.as_deref().is_some_and(|p| !p.trim().is_empty()), "{opencode:?}");
+ assert_eq!(opencode.install, "npm install -g opencode-ai");
+ assert_eq!(opencode.argv.get(1).map(String::as_str), Some("acp"), "still offered with its ACP arguments");
+ let copilot = found("copilot");
+ assert!(copilot.problem.as_deref().is_some_and(|p| !p.trim().is_empty()), "{copilot:?}");
+ #[cfg(windows)]
+ assert!(
+ copilot.problem.as_deref().is_some_and(|p| (p.contains("216") || p.contains("193")) && p.contains("copilot.exe") && !p.contains("%1")),
+ "the system's reason, naming the program: {copilot:?}"
+ );
+ // Silent but failing: the exit status is the reason.
+ let grok = found("grok");
+ assert!(grok.problem.as_deref().is_some_and(|p| p.contains('3')), "{grok:?}");
+
+ let qwen = found("qwen");
+ assert_eq!((qwen.version.as_deref(), qwen.problem.as_deref()), (Some("0.1.2"), None));
+ let goose = found("goose");
+ assert_eq!((goose.version.as_deref(), goose.problem.as_deref()), (None, None));
+ assert!(d.found.iter().all(|f| f.problem.as_ref().is_none_or(|p| p.chars().count() <= PROBLEM_CHARS)));
+ let _ = std::fs::remove_dir_all(root);
+ }
+
/// A launcher can start SolidCraft with a PATH that lacks Node (#9297). On Windows, Node's
/// install folders are searched after it, so `node` is found, and an agent started with these
/// folders as its PATH (`command_for`) finds it too.
@@ -623,7 +738,7 @@ mod tests {
let agent = find_in("solidcraft-test-agent", &search_dirs()).unwrap();
// Generous limits: both answer at once, but a whole test run on a loaded machine
// can keep `env`, the shell and the script from starting within 3 s.
- assert_eq!(version(&agent, Duration::from_secs(20)).as_deref(), Some("1.2.3"));
+ assert_eq!(probe(&agent, Duration::from_secs(20)).version.as_deref(), Some("1.2.3"));
let mut p = AgentProcess::spawn(&[agent.to_string_lossy().into_owned()], &root, &[], || {}).unwrap();
let message = serde_json::json!({"id": 1, "method": "initialize"});
p.send(&message);
diff --git a/crates/ui-egui/src/agent_chat/mod.rs b/crates/ui-egui/src/agent_chat/mod.rs
index 30fb5b07f5..3275803696 100644
--- a/crates/ui-egui/src/agent_chat/mod.rs
+++ b/crates/ui-egui/src/agent_chat/mod.rs
@@ -936,6 +936,11 @@ pub fn connect(app: &mut SolveApp, ctx: &egui::Context) {
} else if cli.is_none() {
chat.notice(tr("ui.agent_chat_no_cli"), true);
}
+ // Found, but it failed when asked its version (#9034): say why and how to reinstall it before
+ // the system's own message arrives. It is still started, in case it only lacks `--version`.
+ if let Some(hint) = entry.problem_hint() {
+ chat.notice(hint, true);
+ }
let bridge = cli.zip(chat.tools_port).map(|(cli, port)| acp::McpBridge { cli, port });
chat.tools_available = Some(bridge.is_some());
let wake = ctx.clone();
@@ -2225,7 +2230,7 @@ pub fn status(app: &SolveApp) -> Value {
#[cfg(not(target_arch = "wasm32"))]
let detection = c.detection.as_ref().map(|d| {
json!({
- "found": d.found.iter().map(|f| json!({"id": f.id, "name": f.name, "argv": f.argv, "version": f.version, "login": f.login.id()})).collect::<Vec<_>>(),
+ "found": d.found.iter().map(|f| json!({"id": f.id, "name": f.name, "argv": f.argv, "version": f.version, "login": f.login.id(), "problem": f.problem})).collect::<Vec<_>>(),
"missing": d.missing.iter().map(|m| json!({"id": m.id, "install": m.install})).collect::<Vec<_>>(),
"ms": d.took_ms,
})
@@ -2242,7 +2247,7 @@ pub fn status(app: &SolveApp) -> Value {
"openAtStart": app.preferences.agent_chat_open_at_start,
"lastAgent": app.preferences.agent_last,
"permissions": app.preferences.ai_permissions.id(),
- "agents": agents::entries(app).iter().map(|e| json!({"id": e.id, "name": e.name, "kind": e.kind.id(), "found": e.found, "version": e.version, "login": e.login, "request_timeout_s": e.kind.is_api().then_some(e.request_timeout_s)})).collect::<Vec<_>>(),
+ "agents": agents::entries(app).iter().map(|e| json!({"id": e.id, "name": e.name, "kind": e.kind.id(), "found": e.found, "version": e.version, "login": e.login, "problem": e.problem, "request_timeout_s": e.kind.is_api().then_some(e.request_timeout_s)})).collect::<Vec<_>>(),
"currentAgent": agents::current(app).map(|e| e.id),
"models": c.models.iter().map(|m| json!({"id": m.id, "name": m.name, "description": m.description})).collect::<Vec<_>>(),
"model": c.model,
diff --git a/crates/ui-egui/src/agent_chat/settings.rs b/crates/ui-egui/src/agent_chat/settings.rs
index 86b78a01ec..92d3b3bc77 100644
--- a/crates/ui-egui/src/agent_chat/settings.rs
+++ b/crates/ui-egui/src/agent_chat/settings.rs
@@ -711,6 +711,8 @@ pub fn dialog(app: &mut SolveApp, ctx: &egui::Context) {
model: s.model.trim().to_string(),
key: false,
request_timeout_s: s.request_timeout_s,
+ problem: None,
+ install: "",
};
let key = Some(s.key.trim().to_string()).filter(|k| !k.is_empty());
let result = match url {
diff --git a/crates/ui-egui/src/agent_chat/tests.rs b/crates/ui-egui/src/agent_chat/tests.rs
index de6a329915..c99c9c7ac1 100644
--- a/crates/ui-egui/src/agent_chat/tests.rs
+++ b/crates/ui-egui/src/agent_chat/tests.rs
@@ -17,6 +17,8 @@ fn app_with_discovered_login() -> SolveApp {
argv: vec!["qwen".into(), "--acp".into()],
version: None,
login: discover::Login::LooksLoggedIn,
+ problem: None,
+ install: "npm install -g @qwen-code/qwen-code",
}],
..Default::default()
});
@@ -2435,6 +2437,34 @@ fn a_connection_that_never_gets_ready_says_connection_failed_and_offers_retry()
assert_eq!(app.agent_chat.state(), State::Failed);
assert!(app.preferences.agent_last.is_empty(), "only an agent that started is remembered");
+ // A found agent that failed its version check (#9034): the picker says it doesn't start, and
+ // connecting says why and how to install it again, besides the system's own message.
+ let mut app = SolveApp::new(solidcraft_engine::Session::default(), crate::Services::default());
+ let reason = "This version of opencode.exe is not compatible with the version of Windows you're running.";
+ app.agent_chat.detection = Some(discover::Detection {
+ found: vec![discover::Found {
+ id: "opencode",
+ name: "OpenCode",
+ argv: vec!["solidcraft-no-such-agent-9034".into(), "acp".into()],
+ version: None,
+ login: discover::Login::Unknown,
+ problem: Some(reason.into()),
+ install: "npm install -g opencode-ai",
+ }],
+ ..Default::default()
+ });
+ let entry = agents::current(&app).unwrap();
+ assert!(entry.detail().contains(reason), "{}", entry.detail());
+ connect(&mut app, &ctx);
+ assert_eq!(app.agent_chat.state(), State::Failed);
+ let told = |needle: &str| app.agent_chat.items.iter().any(|i| matches!(i, Item::Notice { text, error: true } if text.contains(needle)));
+ assert!(told(reason) && told("npm install -g opencode-ai") && told("OpenCode"), "{:?}", app.agent_chat.items);
+ assert_eq!(status(&app)["agents"][0]["problem"], reason);
+ // One that answered has nothing to say.
+ let mut fine = entry.clone();
+ fine.problem = None;
+ assert_eq!(fine.problem_hint(), None);
+
// No agent at all: the picker opens on what to install.
let mut app = SolveApp::new(solidcraft_engine::Session::default(), crate::Services::default());
app.agent_chat.detection = Some(discover::Detection::default());
diff --git a/docs/agent-chat.md b/docs/agent-chat.md
index 7341489c25..895b0a87cb 100644
--- a/docs/agent-chat.md
+++ b/docs/agent-chat.md
@@ -187,7 +187,12 @@ doesn't change the last known login state.
| GitHub Copilot CLI, Qwen Code, goose | listed with their install command when missing |
The panel lists agents that aren't installed with their install command and a **Copy** button.
-**Refresh** looks again after you install one. **Test** starts an agent briefly, asks it for a
+**Refresh** looks again after you install one. An agent whose program is there but fails its
+`--version` check without printing a version (an install that didn't finish, such as an npm
+install whose setup script didn't run, or a program built for another kind of computer) is
+still listed, marked **does not start** with the system's reason. Connecting to it first says
+why and gives its install command; reinstall it until `--version` works in a terminal, then
+press **Refresh**. A check that runs out of time is not counted as a failure. **Test** starts an agent briefly, asks it for a
session and ends it again.
### Flatpak