diff --git a/Cargo.lock b/Cargo.lock index 986ddfde..e2d9ff19 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -432,7 +432,7 @@ dependencies = [ [[package]] name = "codegraph-bench" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "clap", @@ -447,7 +447,7 @@ dependencies = [ [[package]] name = "codegraph-core" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "serde", @@ -463,7 +463,7 @@ dependencies = [ [[package]] name = "codegraph-daemon" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "codegraph-core", @@ -483,7 +483,7 @@ dependencies = [ [[package]] name = "codegraph-extract" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "codegraph-core", @@ -525,7 +525,7 @@ dependencies = [ [[package]] name = "codegraph-graph" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "codegraph-core", @@ -539,7 +539,7 @@ dependencies = [ [[package]] name = "codegraph-mcp" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "axum", @@ -562,7 +562,7 @@ dependencies = [ [[package]] name = "codegraph-resolve" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "codegraph-core", @@ -576,7 +576,7 @@ dependencies = [ [[package]] name = "codegraph-rs" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "assert_cmd", @@ -610,7 +610,7 @@ dependencies = [ [[package]] name = "codegraph-store" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "codegraph-core", @@ -622,7 +622,7 @@ dependencies = [ [[package]] name = "codegraph-watch" -version = "0.27.0" +version = "0.28.2" dependencies = [ "anyhow", "codegraph-core", diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs index 12af3e11..566b825b 100644 --- a/crates/codegraph-cli/src/main.rs +++ b/crates/codegraph-cli/src/main.rs @@ -1377,10 +1377,7 @@ fn cmd_serve( .context("running as detached MCP daemon"); } ServeMode::SpawnOrProxy => { - if let Some(result) = spawn_or_proxy(project.clone(), &project_root, no_watch) { - return result; - } - return serve_direct(project, &project_root, no_watch, explicit_path); + return serve_spawn_or_proxy(project, &project_root, no_watch, explicit_path); } } } @@ -2079,45 +2076,81 @@ fn start_direct_watcher( const DAEMON_SOCKET_POLL_INTERVAL: std::time::Duration = std::time::Duration::from_millis(25); const DAEMON_SOCKET_POLL_TIMEOUT: std::time::Duration = std::time::Duration::from_millis(400); -/// Spawn the shared daemon if needed, poll for its socket, then run the real -/// proxy. Returns `Some(Ok(()))` when the proxy bridged the session (caller -/// must NOT also serve direct), or `None` when the proxy could not attach -/// (daemon spawn failed, socket never appeared, or a version mismatch) — the -/// caller then transparently falls back to direct serving. -fn spawn_or_proxy( - _project: Option, +/// What a `SpawnOrProxy` serve should do given whether a shared daemon is +/// already live for this project. Split out as a pure decision so the cold vs +/// warm handshake behavior is unit-testable without touching sockets/processes. +#[derive(Debug, PartialEq, Eq)] +pub enum ColdStartAction { + /// A daemon is ALREADY running: attach to it via the real proxy (the proxy + /// answers `initialize`/`tools/list` locally and forwards tool calls). Fast. + ProxyToRunningDaemon, + /// COLD start (no live daemon): spawn the shared daemon FIRE-AND-FORGET for + /// the NEXT session's warm attach, but serve THIS session DIRECT immediately + /// so the MCP handshake is answered without waiting on daemon readiness. + SpawnDaemonAndServeDirect, +} + +/// Decide the `SpawnOrProxy` handshake strategy. WARM (daemon live) proxies; +/// COLD spawns the shared daemon fire-and-forget and serves this session direct. +pub fn cold_start_action(daemon_running: bool) -> ColdStartAction { + if daemon_running { + ColdStartAction::ProxyToRunningDaemon + } else { + ColdStartAction::SpawnDaemonAndServeDirect + } +} + +/// `SpawnOrProxy` serve entry point. On a WARM start (a shared daemon is already +/// live) it attaches via [`run_proxy`], falling back to direct serving only if +/// the attach fails. On a COLD start (no live daemon) it spawns the shared +/// daemon FIRE-AND-FORGET — so the NEXT session attaches warm — and immediately +/// serves THIS session DIRECT, answering the MCP `initialize`/`tools/list` +/// handshake without blocking on daemon socket readiness. This is the fix for +/// the cold-start handshake race (opencode marking codegraph `failed` when the +/// spawn→poll→proxy→heal prelude exceeded its MCP init timeout under load). +fn serve_spawn_or_proxy( + project: Option, project_root: &Path, no_watch: bool, -) -> Option> { + explicit_path: bool, +) -> Result<()> { tracing::debug!( pid_path = %codegraph_daemon::daemon_pid_path(project_root).display(), socket_path = %codegraph_daemon::recorded_socket_path(project_root).display(), - "spawn_or_proxy: begin" + "serve_spawn_or_proxy: begin" ); - if daemon_already_running(project_root) { - tracing::debug!("spawn_or_proxy: attaching to existing daemon"); - } else { - match std::env::current_exe() { - Ok(exe) => { - if let Err(err) = - codegraph_daemon::spawn_detached_daemon(&exe, project_root, no_watch) - { - tracing::debug!(error = %err, "spawn_or_proxy: daemon spawn failed; falling back to direct"); - return None; - } - tracing::debug!("spawn_or_proxy: spawned new daemon"); - poll_for_daemon_socket(project_root); - } - Err(err) => { - tracing::debug!(error = %err, "spawn_or_proxy: current_exe unavailable; falling back to direct"); - return None; + match cold_start_action(daemon_already_running(project_root)) { + ColdStartAction::ProxyToRunningDaemon => { + tracing::debug!("serve_spawn_or_proxy: attaching to existing daemon (warm)"); + if let Some(result) = proxy_to_running_daemon(project_root) { + return result; } + serve_direct(project, project_root, no_watch, explicit_path) + } + ColdStartAction::SpawnDaemonAndServeDirect => { + // Cold: kick off the shared daemon for FUTURE sessions, then serve + // this session direct immediately. The spawn is best-effort and + // idempotent — `start_or_attach` (via the daemon's pid lock) makes N + // concurrent cold sessions converge on at most one daemon, and a + // failed/lost race just means this session serves direct (which it + // does anyway). We deliberately do NOT poll or proxy here: that + // prelude is exactly what blew past opencode's handshake timeout. + spawn_shared_daemon_best_effort(project_root, no_watch); + serve_direct(project, project_root, no_watch, explicit_path) } } +} +/// Attach to an ALREADY-running shared daemon via the real proxy. Returns +/// `Some(Ok(()))` when the proxy bridged the session (caller must NOT also serve +/// direct), or `None` when it could not attach (socket gone, version mismatch, +/// or connect error) — the caller then falls back to direct serving. Unchanged +/// proxy semantics: `run_proxy` answers `initialize`/`tools/list` locally and +/// forwards tool calls; its fd half-close / ppid-watchdog teardown is untouched. +fn proxy_to_running_daemon(project_root: &Path) -> Option> { let socket_path = codegraph_daemon::recorded_socket_path(project_root); if !socket_path.exists() { - tracing::debug!("spawn_or_proxy: daemon socket never appeared; falling back to direct"); + tracing::debug!("proxy_to_running_daemon: daemon socket missing; falling back to direct"); heal_stale_daemon_if_dead(project_root); return None; } @@ -2132,17 +2165,40 @@ fn spawn_or_proxy( ) { Ok(codegraph_daemon::ProxyOutcome::Proxied) => Some(Ok(())), Ok(codegraph_daemon::ProxyOutcome::VersionMismatch) => { - tracing::debug!("spawn_or_proxy: daemon version mismatch; falling back to direct"); + tracing::debug!( + "proxy_to_running_daemon: daemon version mismatch; falling back to direct" + ); None } Err(err) => { - tracing::debug!(error = %err, "spawn_or_proxy: proxy attach failed; falling back to direct"); + tracing::debug!(error = %err, "proxy_to_running_daemon: proxy attach failed; falling back to direct"); heal_stale_daemon_if_dead(project_root); None } } } +/// Fire-and-forget spawn of the shared daemon on a cold start so subsequent +/// sessions attach warm. Best-effort: errors are logged and swallowed (this +/// session serves direct regardless), and the daemon's own pid lock guarantees +/// N concurrent cold starts do not produce N daemons. Does NOT block on socket +/// readiness — that would reintroduce the handshake stall this fix removes. +fn spawn_shared_daemon_best_effort(project_root: &Path, no_watch: bool) { + match std::env::current_exe() { + Ok(exe) => match codegraph_daemon::spawn_detached_daemon(&exe, project_root, no_watch) { + Ok(()) => { + tracing::debug!("serve_spawn_or_proxy: spawned shared daemon (fire-and-forget)"); + } + Err(err) => { + tracing::debug!(error = %err, "serve_spawn_or_proxy: daemon spawn failed; serving direct only"); + } + }, + Err(err) => { + tracing::debug!(error = %err, "serve_spawn_or_proxy: current_exe unavailable; serving direct only"); + } + } +} + /// Self-heal a project's stale daemon artifacts on a failed proxy attach when /// the recorded pid is not alive (Fix A): removes the dead daemon's leftover /// `daemon.sock` + pid lock so the NEXT `serve --mcp` spawns a fresh daemon @@ -2212,9 +2268,9 @@ pub fn select_serve_mode( #[cfg(test)] mod serve_mode_tests { use super::{ - ServeMode, debug_enabled, effective_log_level, emit_serve_startup_debug, - guard_indexable_root, select_serve_mode, should_run_daemon_services, - should_run_serve_services, + ColdStartAction, ServeMode, cold_start_action, debug_enabled, effective_log_level, + emit_serve_startup_debug, guard_indexable_root, select_serve_mode, + should_run_daemon_services, should_run_serve_services, }; use std::path::Path; use std::sync::Mutex; @@ -2296,6 +2352,20 @@ mod serve_mode_tests { ); } + #[test] + fn cold_start_action_warm_proxies_cold_spawns_then_serves_direct() { + assert_eq!( + cold_start_action(true), + ColdStartAction::ProxyToRunningDaemon, + "a live daemon ⇒ attach via proxy (warm path unchanged)" + ); + assert_eq!( + cold_start_action(false), + ColdStartAction::SpawnDaemonAndServeDirect, + "no live daemon ⇒ fire-and-forget spawn + serve direct immediately (no blocking proxy)" + ); + } + #[test] fn serve_services_gate_skips_unindexed_bare_cwd_but_runs_when_explicit_or_indexed() { let seq = std::time::SystemTime::now() diff --git a/crates/codegraph-cli/tests/cold_start_handshake.rs b/crates/codegraph-cli/tests/cold_start_handshake.rs new file mode 100644 index 00000000..7cca3b0d --- /dev/null +++ b/crates/codegraph-cli/tests/cold_start_handshake.rs @@ -0,0 +1,294 @@ +//! Cold-start MCP handshake latency guard (fix/cli-cold-start-handshake-race). +//! +//! Regression guard for the cold-start handshake race: opencode marked +//! codegraph `failed` because a COLD `serve --mcp` used to poll+proxy a +//! freshly-spawned shared daemon before answering `initialize`, and that +//! spawn→poll→proxy prelude blew past the MCP init timeout. +//! +//! The fix makes the COLD `SpawnOrProxy` path fire-and-forget the shared daemon +//! (`spawn_shared_daemon_best_effort`) and then serve THIS session DIRECT +//! immediately — so the handshake is answered fast, without blocking on daemon +//! socket readiness. This test exercises the real cold path (NO +//! `CODEGRAPH_NO_DAEMON`, so `serve_spawn_or_proxy` is not forced to direct +//! mode) and asserts: +//! +//! (a) the `initialize` response arrives within a STRICT bound (< 2s), +//! (b) the `tools/list` response arrives within the same strict bound and its +//! tool list CONTAINS `codegraph_search` AND `codegraph_explore`. +//! +//! The 2s bound is the whole point of the fix: because the cold path no longer +//! blocks on the daemon prelude, the handshake must be near-instant. It is also +//! the same bound `catch_up.rs` uses for its forced-direct first-call latency, +//! so it is a proven, non-flaky ceiling on a loaded box. +//! +//! Teardown reaps BOTH the serve child (RAII `ServeProcess`) AND the shared +//! daemon the cold path fire-and-forget spawned: we read the daemon pid from +//! `/.codegraph/daemon.pid` and kill it, so no orphan `codegraph` +//! daemon process leaks. + +#![cfg(unix)] + +use std::fs; +use std::io::{BufRead, BufReader, Write}; +use std::path::{Path, PathBuf}; +use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio}; +use std::time::{Duration, Instant}; + +/// Strict handshake latency bound. The cold path no longer blocks on the daemon +/// spawn→poll→proxy prelude, so both `initialize` and `tools/list` must return +/// near-instantly; 2s is the same proven ceiling `catch_up.rs` uses. +const HANDSHAKE_BOUND: Duration = Duration::from_secs(2); + +fn bin() -> PathBuf { + PathBuf::from(env!("CARGO_BIN_EXE_codegraph")) +} + +fn workspace_root() -> PathBuf { + Path::new(env!("CARGO_MANIFEST_DIR")) + .parent() + .and_then(Path::parent) + .expect("codegraph-cli is under crates/") + .to_path_buf() +} + +fn mini_fixture() -> PathBuf { + workspace_root().join("crates/codegraph-bench/fixtures/mini") +} + +fn copy_tree(src: &Path, dst: &Path) { + fs::create_dir_all(dst).unwrap(); + for entry in fs::read_dir(src).unwrap() { + let entry = entry.unwrap(); + let from = entry.path(); + let to = dst.join(entry.file_name()); + if from.is_dir() { + copy_tree(&from, &to); + } else { + fs::copy(&from, &to).unwrap(); + } + } +} + +struct TestDir { + path: PathBuf, +} + +impl TestDir { + fn new(label: &str) -> Self { + let path = std::env::temp_dir().join(format!( + "codegraph-cli-coldstart-{label}-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos() + )); + fs::create_dir_all(&path).unwrap(); + Self { path } + } + + fn path(&self) -> &Path { + &self.path + } +} + +impl Drop for TestDir { + fn drop(&mut self) { + let _ = fs::remove_dir_all(&self.path); + } +} + +fn cli(args: &[&str]) -> (String, String, bool) { + let output = Command::new(bin()) + .args(args) + .output() + .expect("run codegraph binary"); + ( + String::from_utf8_lossy(&output.stdout).into_owned(), + String::from_utf8_lossy(&output.stderr).into_owned(), + output.status.success(), + ) +} + +/// A live COLD `serve --mcp` child driven over line-delimited JSON-RPC. Killed + +/// reaped on drop so no orphan serve process leaks. The `BufReader` is created +/// ONCE and held for the process lifetime (re-creating it per read would drop +/// buffered bytes). Modeled on `catch_up.rs`'s `ServeProcess`, but WITHOUT +/// `CODEGRAPH_NO_DAEMON` so it exercises the real cold `SpawnOrProxy` path. +struct ServeProcess { + child: Child, + stdin: ChildStdin, + reader: BufReader, +} + +impl ServeProcess { + fn spawn(project: &Path) -> Self { + let mut cmd = Command::new(bin()); + cmd.arg("serve") + .arg("--mcp") + .arg("--path") + .arg(project) + // COLD start: NO CODEGRAPH_NO_DAEMON — we want serve_spawn_or_proxy + // to take the real cold path (fire-and-forget daemon + serve direct), + // NOT forced-direct mode. `--no-watch` keeps the fire-and-forget + // daemon watcher-free so teardown is clean; it does not change the + // cold decision (daemon still spawns, this session still serves + // direct). + .arg("--no-watch") + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::null()); + let mut child = cmd.spawn().expect("spawn serve --mcp (cold)"); + let stdin = child.stdin.take().expect("serve stdin"); + let stdout = child.stdout.take().expect("serve stdout"); + Self { + child, + stdin, + reader: BufReader::new(stdout), + } + } + + fn send(&mut self, line: &str) { + self.stdin + .write_all(line.as_bytes()) + .expect("write request"); + self.stdin.write_all(b"\n").expect("write newline"); + self.stdin.flush().expect("flush request"); + } + + /// Read line-delimited JSON-RPC responses until one carries `want_id`, + /// skipping notifications / blank lines. Returns `None` on EOF or `deadline`. + fn read_response(&mut self, want_id: u64, deadline: Instant) -> Option { + loop { + if Instant::now() > deadline { + return None; + } + let mut line = String::new(); + match self.reader.read_line(&mut line) { + Ok(0) => return None, + Ok(_) => { + let trimmed = line.trim(); + if trimmed.is_empty() { + continue; + } + if let Ok(value) = serde_json::from_str::(trimmed) + && value.get("id").and_then(serde_json::Value::as_u64) == Some(want_id) + { + return Some(value); + } + } + Err(_) => return None, + } + } + } +} + +impl Drop for ServeProcess { + fn drop(&mut self) { + let _ = self.child.kill(); + let _ = self.child.wait(); + } +} + +/// Read the live daemon pid recorded under `/.codegraph/daemon.pid`, if +/// any. The cold path fire-and-forget spawns this daemon; we reap it in teardown +/// so no orphan `codegraph` daemon process survives the test. +fn recorded_daemon_pid(project: &Path) -> Option { + let pid_path = codegraph_daemon::daemon_pid_path(project); + let raw = fs::read_to_string(&pid_path).ok()?; + codegraph_daemon::decode_lock_info(&raw) + .filter(|info| info.pid > 0) + .map(|info| info.pid) +} + +/// Poll for the fire-and-forget daemon to record a live pid, up to `timeout`. +fn poll_for_daemon_pid(project: &Path, timeout: Duration) -> Option { + let deadline = Instant::now() + timeout; + while Instant::now() < deadline { + if let Some(pid) = recorded_daemon_pid(project) + && codegraph_daemon::is_process_alive(pid) + { + return Some(pid); + } + std::thread::sleep(Duration::from_millis(25)); + } + recorded_daemon_pid(project) +} + +fn kill_pid(pid: u32) { + let _ = Command::new("kill").arg("-9").arg(pid.to_string()).status(); +} + +#[test] +fn cold_start_serve_answers_handshake_within_bound() { + let dir = TestDir::new("handshake"); + let project = dir.path().join("mini"); + copy_tree(&mini_fixture(), &project); + + // Index the project so the served graph is ready (no daemon involved yet). + let (out, err, ok) = cli(&["init", project.to_str().unwrap()]); + assert!(ok, "init failed: stdout={out} stderr={err}"); + let (out, err, ok) = cli(&["index", "--force", project.to_str().unwrap()]); + assert!(ok, "index --force failed: stdout={out} stderr={err}"); + + // COLD start: no shared daemon is live yet, so serve_spawn_or_proxy takes + // the cold path (fire-and-forget daemon spawn + serve THIS session direct). + let mut serve = ServeProcess::spawn(&project); + + // (a) initialize must return within the strict bound. + serve.send(r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cold-start-test","version":"0"}}}"#); + let init_started = Instant::now(); + let init = serve + .read_response(1, init_started + HANDSHAKE_BOUND) + .expect("initialize must respond within the cold-start handshake bound"); + let init_latency = init_started.elapsed(); + assert!( + init_latency < HANDSHAKE_BOUND, + "cold-start initialize must not block on the daemon prelude; took {init_latency:?}" + ); + assert_eq!( + init["result"]["serverInfo"]["name"], + serde_json::json!("codegraph"), + "cold-start serve must identify as codegraph: {init}" + ); + + // MCP spec: send the initialized notification after initialize. + serve.send(r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#); + + // (b) tools/list must return within the strict bound AND expose the + // codegraph tools (registered without a server prefix in the MCP engine). + serve.send(r#"{"jsonrpc":"2.0","id":2,"method":"tools/list"}"#); + let list_started = Instant::now(); + let list = serve + .read_response(2, list_started + HANDSHAKE_BOUND) + .expect("tools/list must respond within the cold-start handshake bound"); + let list_latency = list_started.elapsed(); + assert!( + list_latency < HANDSHAKE_BOUND, + "cold-start tools/list must not block on the daemon prelude; took {list_latency:?}" + ); + + let names: Vec = list["result"]["tools"] + .as_array() + .expect("tools/list result must carry a tools array") + .iter() + .filter_map(|tool| tool["name"].as_str().map(str::to_owned)) + .collect(); + assert!( + names.iter().any(|n| n == "codegraph_search"), + "tools/list must include codegraph_search; got {names:?}" + ); + assert!( + names.iter().any(|n| n == "codegraph_explore"), + "tools/list must include codegraph_explore; got {names:?}" + ); + + // TEARDOWN: reap the fire-and-forget shared daemon the cold path spawned so + // no orphan `codegraph` daemon process leaks. The daemon binds its socket + + // writes its pid asynchronously; poll briefly for it, then kill by pid. + if let Some(daemon_pid) = poll_for_daemon_pid(&project, Duration::from_secs(3)) { + kill_pid(daemon_pid); + } + // The serve child is killed+reaped by ServeProcess::drop; the temp project + // tree (incl. .codegraph/) is removed by TestDir::drop. +}