feat(runtime): enhance PATH at startup for all downstream spawn sites

AGENTS.md

@@ -134,6 +134,21 @@ The bun version is pinned in
 `[package.metadata.aionui-runtime] bun_version = "..."`. Upgrading bun is
 a one-line change — no source edits required.
 
+### Startup PATH Enhancement
+
+`fn main()` calls `aionui_runtime::enhance_process_path()` **before** the
+tokio runtime starts, so every downstream `which::which(...)` and
+`Command::new(...)` — including the existing spawn sites across the
+workspace — inherits an enriched `PATH`. Three layers are merged in priority
+order: bundled bun directory → platform extra bins (`~/.bun/bin`,
+`~/.cargo/bin`, `~/.local/bin`, Windows `%APPDATA%\npm`, Git, Scoop, …) →
+current PATH → login-shell `$PATH` (Unix, 3 s timeout). The call is
+`unsafe` because Rust 2024 requires a single-threaded precondition for
+`env::set_var`; `main()` runs this as its very first statement to
+satisfy the invariant. A `startup: PATH ready path_segments=… path_len=…`
+info log confirms the enhancement at each run (no full PATH content is
+logged at `info` level).
+
 ### Pushing Code
 
 Always use `just push` instead of `git push`.

crates/aionui-app/Cargo.toml

@@ -33,6 +33,7 @@ aionui-channel.workspace = true
 aionui-team.workspace = true
 aionui-cron.workspace = true
 aionui-assistant.workspace = true
+aionui-runtime.workspace = true
 axum.workspace = true
 dirs.workspace = true
 tokio.workspace = true

crates/aionui-app/src/main.rs

@@ -77,8 +77,17 @@ fn init_tracing(log_dir: &Path, log_level: Option<&str>) -> tracing_appender::no
     guard
 }
 
-#[tokio::main]
-async fn main() -> Result<ExitCode> {
+fn main() -> Result<ExitCode> {
+    // SAFETY: called before any worker thread exists (including the tokio
+    // runtime constructed below). Rust 2024 requires `unsafe` for
+    // `std::env::set_var` invoked inside `enhance_process_path`.
+    let merged_path = unsafe { aionui_runtime::enhance_process_path() };
+
+    let runtime = tokio::runtime::Builder::new_multi_thread().enable_all().build()?;
+    runtime.block_on(async_main(merged_path))
+}
+
+async fn async_main(merged_path: String) -> Result<ExitCode> {
     // mcp-bridge / mcp-guide-stdio subcommands: live entirely outside the main
     // HTTP server and must not touch the database, logging setup, or `AppServices`.
     let mut argv = std::env::args();
@@ -95,6 +104,12 @@ async fn main() -> Result<ExitCode> {
     let log_dir = cli.log_dir.unwrap_or_else(|| Path::new(&cli.data_dir).join("logs"));
     let _log_guard = init_tracing(&log_dir, cli.log_level.as_deref());
 
+    tracing::info!(
+        path_segments = merged_path.split(if cfg!(windows) { ';' } else { ':' }).count(),
+        path_len = merged_path.len(),
+        "startup: PATH ready"
+    );
+
     let config = AppConfig {
         host: cli.host,
         port: cli.port,

crates/aionui-runtime/Cargo.toml

@@ -32,3 +32,6 @@ tempfile.workspace = true
 zstd.workspace = true
 sha2.workspace = true
 hex.workspace = true
+
+[target.'cfg(unix)'.dependencies]
+wait-timeout = "0.2"

crates/aionui-runtime/src/lib.rs

@@ -9,8 +9,10 @@ mod cache;
 mod embed;
 mod extract;
 mod resolver;
+mod shell_env;
 
 pub use resolver::{ResolveError, bun_bin_dir, resolve_bun};
+pub use shell_env::enhance_process_path;
 
 #[cfg(test)]
 #[path = "../build_support.rs"]