fix(socktop): explain how to install socktop_agent when demo mode can't find it

Demo mode spawns a socktop_agent child process, but the agent is a separate
crate that `cargo install socktop` does not pull in. When it was missing, the
raw spawn error propagated to main and printed as
`Error: Os { code: 2, kind: NotFound, message: "No such file or directory" }`,
which gives the user nothing to act on.

Introduce DemoAgentError so a NotFound spawn failure is distinguishable from
other io errors, and print the path we looked for plus the `cargo install
socktop_agent` fix. Other spawn errors still propagate as before.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Cargo.lock

@@ -99,9 +99,9 @@ checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
 [[package]]
 name = "aws-lc-rs"
-version = "1.15.0"
+version = "1.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5932a7d9d28b0d2ea34c6b3779d35e3dd6f6345317c34e73438c4f1f29144151"
+checksum = "4342d8937fc7e5dd9b1c60292261c0670c882a2cd1719cfc11b1af41731e32ad"
 dependencies = [
  "aws-lc-sys",
  "zeroize",
@@ -109,15 +109,15 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-sys"
-version = "0.33.0"
+version = "0.42.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1826f2e4cfc2cd19ee53c42fbf68e2f81ec21108e0b7ecf6a71cf062137360fc"
+checksum = "6d9ceb1da931507a12f4fccea479dccd00da1943e1b4ae72d8e502d707361444"
 dependencies = [
- "bindgen",
  "cc",
  "cmake",
  "dunce",
  "fs_extra",
+ "pkg-config",
 ]
 
 [[package]]
@@ -218,26 +218,6 @@ version = "0.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
-[[package]]
-name = "bindgen"
-version = "0.72.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
-dependencies = [
- "bitflags 2.10.0",
- "cexpr",
- "clang-sys",
- "itertools 0.13.0",
- "log",
- "prettyplease",
- "proc-macro2",
- "quote",
- "regex",
- "rustc-hash",
- "shlex",
- "syn 2.0.110",
-]
-
 [[package]]
 name = "bit-set"
 version = "0.5.3"
@@ -330,15 +310,6 @@ dependencies = [
  "shlex",
 ]
 
-[[package]]
-name = "cexpr"
-version = "0.6.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
-dependencies = [
- "nom",
-]
-
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
@@ -363,17 +334,6 @@ dependencies = [
  "windows-link 0.2.1",
 ]
 
-[[package]]
-name = "clang-sys"
-version = "1.8.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4"
-dependencies = [
- "glob",
- "libc",
- "libloading",
-]
-
 [[package]]
 name = "cmake"
 version = "0.1.54"
@@ -913,12 +873,6 @@ dependencies = [
  "wmi",
 ]
 
-[[package]]
-name = "glob"
-version = "0.3.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
-
 [[package]]
 name = "h2"
 version = "0.4.12"
@@ -1247,15 +1201,6 @@ dependencies = [
  "mach2",
 ]
 
-[[package]]
-name = "itertools"
-version = "0.13.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
-dependencies = [
- "either",
-]
-
 [[package]]
 name = "itertools"
 version = "0.14.0"
@@ -1796,6 +1741,12 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
 
+[[package]]
+name = "pkg-config"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
+
 [[package]]
 name = "portable-atomic"
 version = "1.13.1"
@@ -1889,7 +1840,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "be769465445e8c1474e9c5dac2018218498557af32d9ed057325ec9a41ae81bf"
 dependencies = [
  "heck",
- "itertools 0.14.0",
+ "itertools",
  "log",
  "multimap",
  "once_cell",
@@ -1909,7 +1860,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a56d757972c98b346a9b766e3f02746cde6dd1cd1d1d563472929fdd74bec4d"
 dependencies = [
  "anyhow",
- "itertools 0.14.0",
+ "itertools",
  "proc-macro2",
  "quote",
  "syn 2.0.110",
@@ -2063,7 +2014,7 @@ dependencies = [
  "compact_str",
  "hashbrown 0.16.0",
  "indoc",
- "itertools 0.14.0",
+ "itertools",
  "kasuari",
  "lru",
  "strum",
@@ -2115,7 +2066,7 @@ dependencies = [
  "hashbrown 0.16.0",
  "indoc",
  "instability",
- "itertools 0.14.0",
+ "itertools",
  "line-clipping",
  "ratatui-core",
  "strum",
@@ -2200,12 +2151,6 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
-[[package]]
-name = "rustc-hash"
-version = "2.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
-
 [[package]]
 name = "rustc_version"
 version = "0.4.1"
@@ -3080,7 +3025,7 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "16b380a1238663e5f8a691f9039c73e1cdae598a30e9855f541d29b08b53e9a5"
 dependencies = [
- "itertools 0.14.0",
+ "itertools",
  "unicode-segmentation",
  "unicode-width",
 ]

socktop/src/main.rs

@@ -382,7 +382,16 @@ fn gather_intervals(
 async fn run_demo_mode(_tls_ca: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
     let port = 3231;
     let url = format!("ws://127.0.0.1:{port}/ws");
-    let child = spawn_demo_agent(port)?;
+    let child = match spawn_demo_agent(port) {
+        Ok(child) => child,
+        // The agent ships as its own binary, so a missing one is a setup problem,
+        // not a crash: tell the user how to fix it instead of dumping an io error.
+        Err(e @ DemoAgentError::NotFound(_)) => {
+            eprintln!("{e}");
+            return Ok(());
+        }
+        Err(e) => return Err(e.into()),
+    };
     let mut app = App::new();
     // Demo mode connects to localhost, so disable hostname verification
     tokio::select! { res=app.run(&url,None,false)=>{ drop(child); res } _=tokio::signal::ctrl_c()=>{ drop(child); Ok(()) } }
@@ -399,9 +408,50 @@ impl Drop for DemoGuard {
         eprintln!("Stopped demo agent on port {}", self.port);
     }
 }
-fn spawn_demo_agent(port: u16) -> Result<DemoGuard, Box<dyn std::error::Error>> {
+#[derive(Debug)]
+enum DemoAgentError {
+    /// The socktop_agent executable could not be located.
+    NotFound(std::path::PathBuf),
+    Io(std::io::Error),
+}
+
+impl std::fmt::Display for DemoAgentError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::NotFound(candidate) => write!(
+                f,
+                "Could not start demo mode: '{}' was not found{}.\n\
+                 \n\
+                 Demo mode runs a local agent, which is shipped as a separate binary\n\
+                 and is not installed alongside the socktop TUI. Install it with:\n\
+                 \n    cargo install socktop_agent\n\n\
+                 then run socktop again. See {} for other install options.",
+                candidate.display(),
+                // A bare file name means find_agent_executable() fell back to a PATH lookup.
+                if candidate.parent().is_none_or(|p| p.as_os_str().is_empty()) {
+                    " on your PATH"
+                } else {
+                    ""
+                },
+                env!("CARGO_PKG_HOMEPAGE"),
+            ),
+            Self::Io(e) => write!(f, "Could not start demo mode: {e}"),
+        }
+    }
+}
+
+impl std::error::Error for DemoAgentError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::NotFound(_) => None,
+            Self::Io(e) => Some(e),
+        }
+    }
+}
+
+fn spawn_demo_agent(port: u16) -> Result<DemoGuard, DemoAgentError> {
     let candidate = find_agent_executable();
-    let mut cmd = std::process::Command::new(candidate);
+    let mut cmd = std::process::Command::new(&candidate);
     cmd.arg("--port").arg(port.to_string());
     cmd.env("SOCKTOP_ENABLE_SSL", "0");
 
@@ -409,7 +459,10 @@ fn spawn_demo_agent(port: u16) -> Result<DemoGuard, Box<dyn std::error::Error>>
     //cmd.env("SOCKTOP_AGENT_GPU", "0");
     //cmd.env("SOCKTOP_AGENT_TEMP", "0");
 
-    let child = cmd.spawn()?;
+    let child = cmd.spawn().map_err(|e| match e.kind() {
+        std::io::ErrorKind::NotFound => DemoAgentError::NotFound(candidate),
+        _ => DemoAgentError::Io(e),
+    })?;
     std::thread::sleep(std::time::Duration::from_millis(300));
     Ok(DemoGuard {
         port,