From ac1b1b774ceea5b1c5e76be3b973da0a25185402 Mon Sep 17 00:00:00 2001 From: sunerpy Date: Sun, 16 Aug 2026 18:44:40 +0800 Subject: [PATCH] fix(init): recover a lockless index root instead of dead-ending MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A failed background daemon start could leave `.codegraph/` holding nothing but `daemon.log`, because the parent created the index root solely to place the child's stdio. That shape is unrecoverable: `init`, `index --force`, `sync` and `uninit --force` all refuse it, and the log itself keeps advising `codegraph init` — the very command the daemon had just made impossible. Only `rm -rf .codegraph` got out. Teach explicit init to take over such a root. The recovery predicate is now bare `ExtractionStatus::Missing`, which holds only when neither state slot exists: any unreadable slot classifies `Corrupt` earlier, so widening the predicate cannot reach authoritative data. Creating the permanent lock is not possessing it. Between `create_new` and the first `try_lock` the file exists unlocked, so a competing writer can acquire it and publish state; `final_path_matches` corroborates inode identity, not namespace state. Re-assert `Missing` while holding the lease and refuse with `LocklessTakeoverStateChanged` otherwise, dropping the lease before any authorization, `phase=building` publication or database mutation. A `test-hooks` checkpoint parks a real `init` child in that pre-lock window so the race is covered deterministically, without sleeps. Stop the spawn from creating an index root just to hold diagnostics: the log redirect now falls back to the null sink when the root is absent, and the daemon refusal no longer claims no log was published when the parent wrote one. `LockNotFound` and lockless `Missing` now name a remedy that works instead of an internal artifact. --- crates/codegraph-cli/src/main.rs | 74 +++- .../codegraph-cli/tests/batch_m_finalizer.rs | 88 +++++ crates/codegraph-cli/tests/batch_m_uninit.rs | 319 +++++++++++++++++- crates/codegraph-daemon/src/spawn.rs | 62 +++- crates/codegraph-store/src/index_lease.rs | 65 +++- crates/codegraph-store/src/rebuild.rs | 69 ++-- 6 files changed, 618 insertions(+), 59 deletions(-) diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs index b9e094b7..285fecc6 100644 --- a/crates/codegraph-cli/src/main.rs +++ b/crates/codegraph-cli/src/main.rs @@ -1384,6 +1384,8 @@ fn recover_dead_owner_sidecars(paths: &codegraph_core::IndexPaths, project_root: /// The returned `Store` OWNS that same lease, so retaining it across pid/socket /// publication requires no second acquisition: there is no nested lock and no /// window between validation and publication for another writer to reclassify. +/// A refusal therefore proves only that this daemon published no pid or socket; +/// the detached parent may already have opened the project-local log redirect. fn authorize_daemon_startup(project_root: &Path) -> Result { let paths = index_paths(project_root)?; recover_dead_owner_sidecars(&paths, project_root); @@ -1404,8 +1406,11 @@ fn authorize_daemon_startup(project_root: &Path) -> Result, json_output: bool) -> Result<()> { .clone() .expect("a non-busy status probe always classifies the namespace"); let owner_mismatch_recoverable = owner_mismatch_only_reason(&resolved).is_some(); - let extraction_status_detail = - status_extraction_detail(&extraction_status, owner_mismatch_recoverable, &project); + let lockless_missing = + extraction_status == ExtractionStatus::Missing && is_lockless_missing_root(&resolved)?; + let extraction_status_detail = if lockless_missing { + lockless_missing_detail(&project, &resolved) + } else { + status_extraction_detail(&extraction_status, owner_mismatch_recoverable, &project) + }; let store = status_open.into_store(); if store.is_none() { if json_output { @@ -1687,6 +1697,9 @@ fn cmd_status(path: Option, json_output: bool) -> Result<()> { json!(format!("codegraph index --force {}", project.display())); } else if owner_mismatch_recoverable { status["recoveryCommand"] = json!(format!("codegraph init {}", project.display())); + } else if lockless_missing { + status["recoveryCommand"] = + json!(format!("codegraph init \"{}\"", project.display())); } print_json(&status)?; } else { @@ -1725,6 +1738,9 @@ fn cmd_status(path: Option, json_output: bool) -> Result<()> { ExtractionStatus::Corrupt { .. } => { println!("Manual recovery is required."); } + ExtractionStatus::Missing if lockless_missing => { + println!("{extraction_status_detail}"); + } _ => { println!("Not initialized"); println!("Run \"codegraph init\" to initialize"); @@ -5447,7 +5463,10 @@ fn explicit_init_observes_readable_current(project: &Path) -> Result { drop(store); Ok(true) } - Err(codegraph_store::StoreError::CurrentTombstoned { .. }) => Ok(false), + Err( + codegraph_store::StoreError::CurrentTombstoned { .. } + | codegraph_store::StoreError::StateWithoutPermanentLock { .. }, + ) => Ok(false), Err(error) => Err(error.into()), } } @@ -5476,8 +5495,9 @@ fn has_lifecycle_namespace(project: &Path) -> bool { } /// Resolve a readable project and report lifecycle-specific recovery without -/// authorizing mutation. Only an all-present-slot OwnerMismatch names explicit -/// init; mixed or other corruption continues to require manual recovery. +/// authorizing mutation. Only an all-present-slot OwnerMismatch or a Missing +/// existing root with no permanent lock names explicit init; mixed or other +/// corruption continues to require manual recovery. fn resolve_required_project(path: Option) -> Result { let start = absolute_path(path.unwrap_or_else(|| PathBuf::from("."))); index_paths(&start)?; @@ -5507,6 +5527,9 @@ fn resolve_required_project(path: Option) -> Result { if first_existing_database_artifact(&paths)?.is_some() { bail!("{}", missing_state_with_database_detail(&project)); } + if is_lockless_missing_root(&paths)? { + bail!("{}", lockless_missing_detail(&project, &paths)); + } bail!( "CodeGraph not initialized in {}; run `codegraph init {}` to create or replace the index", project.display(), @@ -5562,6 +5585,43 @@ fn missing_state_with_database_detail(project: &Path) -> String { ) } +/// Detect the recoverable filesystem shape after the caller has classified the +/// namespace Missing. Both path probes are non-following and inspection errors +/// propagate, so aliases and inaccessible entries cannot masquerade as recovery. +fn is_lockless_missing_root(paths: &codegraph_core::IndexPaths) -> Result { + let root = paths.current_root(); + let root_metadata = match fs::symlink_metadata(root) { + Ok(metadata) => metadata, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(false), + Err(error) => { + return Err(error).with_context(|| format!("failed to inspect {}", root.display())); + } + }; + if !root_metadata.file_type().is_dir() { + return Ok(false); + } + + let lock = paths.permanent_lock(); + match fs::symlink_metadata(&lock) { + Ok(_) => Ok(false), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(true), + Err(error) => Err(error).with_context(|| format!("failed to inspect {}", lock.display())), + } +} + +fn lockless_missing_detail(project: &Path, paths: &codegraph_core::IndexPaths) -> String { + let lock = paths.permanent_lock(); + let root = lock + .parent() + .expect("the permanent lock always belongs to the current index root"); + format!( + "CodeGraph index directory exists at {}, but its permanent lock is missing at {}; a failed background daemon start can leave this stale namespace. Run `codegraph init \"{}\"` to create the lock and rebuild the index.", + root.display(), + lock.display(), + project.display() + ) +} + fn resolve_required_rebuild_project(path: Option) -> Result { let start = absolute_path(path.unwrap_or_else(|| PathBuf::from("."))); index_paths(&start)?; diff --git a/crates/codegraph-cli/tests/batch_m_finalizer.rs b/crates/codegraph-cli/tests/batch_m_finalizer.rs index 9306944a..6720e38e 100644 --- a/crates/codegraph-cli/tests/batch_m_finalizer.rs +++ b/crates/codegraph-cli/tests/batch_m_finalizer.rs @@ -234,6 +234,94 @@ fn slot_bytes(paths: &IndexPaths) -> [Option>; 2] { }) } +fn lock_not_found_error(paths: &IndexPaths) -> String { + format!( + "existing index namespace has no permanent lock file at {}; a failed background daemon start can leave this stale shape. Run `codegraph status` from the project root to classify it; only `State: missing` is safe to recover with `codegraph init`.", + paths.permanent_lock().display() + ) +} + +fn wait_for_daemon_error(log: &Path) -> String { + let until = Instant::now() + Duration::from_secs(10); + while Instant::now() < until { + if let Ok(contents) = std::fs::read_to_string(log) { + let normalized = normalize(&contents); + if contents.ends_with('\n') + && normalized.lines().any(|line| { + line.strip_prefix("Error: ") + .is_some_and(|body| !body.is_empty()) + }) + { + return final_error_body(&contents); + } + } + std::thread::yield_now(); + } + panic!( + "detached daemon did not publish its final error to {}", + log.display() + ); +} + +#[test] +fn lockless_root_recovery_building_without_lock_refuses_init_unchanged() { + let dir = TestDir::new("lockless-building-init"); + let project = dir.path().join("mini"); + copy_tree(&mini_fixture(), &project); + let paths = IndexPaths::resolve(&project, None).expect("resolve default index paths"); + stage_interrupted_building(&paths, false); + let before = slot_bytes(&paths); + std::fs::remove_file(paths.permanent_lock()).expect("remove permanent lock"); + + let init = run_in( + dir.path(), + &["init", project.to_str().expect("UTF-8 project path")], + ); + assert!(!init.ok, "lockless Building must refuse init"); + assert_eq!(normalize(&init.stdout), ""); + assert_eq!(final_error_body(&init.stderr), lock_not_found_error(&paths)); + assert_eq!(slot_bytes(&paths), before); + assert!(!paths.permanent_lock().exists()); + assert!(!paths.current_db().exists()); + assert_eq!( + Store::extraction_status(&paths), + ExtractionStatus::Building { + built: codegraph_store::CURRENT_EXTRACTION_VERSION, + } + ); +} + +#[test] +fn lockless_root_recovery_daemon_refusal_reports_only_pid_socket_guarantee() { + let dir = TestDir::new("lockless-daemon-refusal"); + let project = dir.path().join("mini"); + copy_tree(&mini_fixture(), &project); + let paths = IndexPaths::resolve(&project, None).expect("resolve default index paths"); + stage_interrupted_building(&paths, false); + let before = slot_bytes(&paths); + let status = Store::extraction_status(&paths); + let store_error = Store::open_for_read(&paths, deadline(), || false) + .expect_err("Building must refuse a read open") + .to_string(); + + codegraph_daemon::spawn_detached_daemon(&bin(), &project, false) + .expect("spawn detached daemon against Building namespace"); + let body = wait_for_daemon_error(&paths.daemon_log()); + assert_eq!( + body, + format!( + "running as detached MCP daemon: refusing to start a daemon for {}: {store_error}; index state is {status} and its uninitialized tombstone is absent. This daemon did not publish a pid or socket; a detached parent may already have opened {}. Run `codegraph status \"{}\"` for state-specific recovery guidance.", + project.display(), + paths.daemon_log().display(), + project.display() + ) + ); + assert!(!paths.daemon_pid().exists()); + assert!(!paths.daemon_socket().exists()); + assert_eq!(slot_bytes(&paths), before); + assert_eq!(Store::extraction_status(&paths), status); +} + #[test] fn building_state_recovery_status_guides_only_stale_building() { let dir = TestDir::new("status-stale-building"); diff --git a/crates/codegraph-cli/tests/batch_m_uninit.rs b/crates/codegraph-cli/tests/batch_m_uninit.rs index c1e3b2b3..a156cb98 100644 --- a/crates/codegraph-cli/tests/batch_m_uninit.rs +++ b/crates/codegraph-cli/tests/batch_m_uninit.rs @@ -7,8 +7,11 @@ //! matrix for every private mutation boundary lives in `codegraph-store`. use std::collections::BTreeMap; +use std::io::{Read, Write}; +use std::net::{SocketAddr, TcpListener, TcpStream}; use std::path::{Path, PathBuf}; -use std::process::Command; +use std::process::{Child, Command, Output, Stdio}; +use std::sync::mpsc::{self, Receiver}; use std::time::{Duration, Instant}; use codegraph_core::IndexPaths; @@ -84,6 +87,13 @@ fn normalize(stream: &str) -> String { stream .lines() .filter(|line| !line.contains("logger initialized")) + .map(|line| { + let is_summary = line.contains(" nodes, ") && line.contains(" edges in "); + match line.rfind(" in ") { + Some(at) if is_summary => line[..at].to_string(), + _ => line.to_string(), + } + }) .collect::>() .join("\n") } @@ -229,6 +239,104 @@ fn deadline() -> Instant { Instant::now() + Duration::from_secs(10) } +fn lock_not_found_error(paths: &IndexPaths) -> String { + format!( + "existing index namespace has no permanent lock file at {}; a failed background daemon start can leave this stale shape. Run `codegraph status` from the project root to classify it; only `State: missing` is safe to recover with `codegraph init`.", + paths.permanent_lock().display() + ) +} + +fn lockless_missing_detail(project: &Path, paths: &IndexPaths) -> String { + format!( + "CodeGraph index directory exists at {}, but its permanent lock is missing at {}; a failed background daemon start can leave this stale namespace. Run `codegraph init \"{}\"` to create the lock and rebuild the index.", + paths.current_root().display(), + paths.permanent_lock().display(), + project.display() + ) +} + +struct LeaseCheckpointBarrier { + address: SocketAddr, + arrived: Receiver<(u8, TcpStream)>, +} + +impl LeaseCheckpointBarrier { + fn start() -> Self { + let listener = TcpListener::bind("127.0.0.1:0").expect("bind lease checkpoint barrier"); + let address = listener.local_addr().expect("lease checkpoint address"); + let (tx, arrived) = mpsc::channel(); + std::thread::spawn(move || { + for stream in listener.incoming() { + let Ok(mut stream) = stream else { return }; + let mut marker = [0_u8; 1]; + if stream.read_exact(&mut marker).is_err() || marker[0] == b'C' { + return; + } + if tx.send((marker[0], stream)).is_err() { + return; + } + } + }); + Self { address, arrived } + } + + fn configure(&self, command: &mut Command) { + command + .env( + "CODEGRAPH_TEST_LEASE_BARRIER_ADDR", + self.address.to_string(), + ) + .env("CODEGRAPH_TEST_LEASE_BARRIER_CHECKPOINT", "handle-opened"); + } + + fn wait_for_handle_opened(&self) -> TcpStream { + match self.arrived.recv_timeout(Duration::from_secs(10)) { + Ok((marker, stream)) => { + assert_eq!( + marker, b'H', + "existing-root creation must stop before locking" + ); + stream + } + Err(error) => { + if let Ok(mut cancel) = TcpStream::connect(self.address) { + let _ = cancel.write_all(b"C"); + } + panic!("handle-opened barrier was not reached before its finite deadline: {error}"); + } + } + } +} + +impl Drop for LeaseCheckpointBarrier { + fn drop(&mut self) { + if let Ok(mut cancel) = TcpStream::connect(self.address) { + let _ = cancel.write_all(b"C"); + } + } +} + +struct ChildGuard(Option); + +impl ChildGuard { + fn finish(mut self) -> Output { + self.0 + .take() + .expect("child still owned") + .wait_with_output() + .expect("collect child output") + } +} + +impl Drop for ChildGuard { + fn drop(&mut self) { + if let Some(child) = self.0.as_mut() { + let _ = child.kill(); + let _ = child.wait(); + } + } +} + fn assert_unrelated_bytes(unrelated_file: &Path, expected: &[u8]) { assert_eq!( std::fs::read(unrelated_file).expect("read untouched unrelated proof"), @@ -950,6 +1058,215 @@ fn building_state_recovery_current_database_remains_readable() { ); } +#[test] +fn lockless_root_recovery_init_preserves_sentinel_and_builds_current() { + let dir = TestDir::new("lockless-only-log-init"); + let project = dir.path().join("mini"); + copy_tree(&mini_fixture(), &project); + let paths = IndexPaths::resolve(&project, None).expect("resolve lockless paths"); + std::fs::create_dir(paths.current_root()).expect("create existing index root"); + let sentinel = b"sentinel daemon diagnostic\n"; + std::fs::write(paths.daemon_log(), sentinel).expect("write sentinel daemon log"); + + let init = run_in( + dir.path(), + &["init", project.to_str().expect("UTF-8 project path")], + ); + assert!( + init.ok, + "lockless Missing root must be recoverable: stdout={}, stderr={}", + init.stdout, init.stderr + ); + assert_eq!( + normalize(&init.stdout), + format!( + "Initialized in {}\nIndexed 3 files\n13 nodes, 21 edges", + project.display() + ) + ); + assert_eq!(normalize(&init.stderr), "Scanning files…"); + assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current); + assert!(paths.permanent_lock().is_file()); + assert!(paths.current_db().is_file()); + assert_eq!( + std::fs::read(paths.daemon_log()).expect("read preserved daemon log"), + sentinel + ); +} + +#[test] +fn lockless_root_recovery_missing_query_and_status_are_actionable() { + let dir = TestDir::new("lockless-missing-diagnostics"); + let project = dir.path().join("project"); + std::fs::create_dir(&project).expect("create project"); + let paths = IndexPaths::resolve(&project, None).expect("resolve lockless paths"); + std::fs::create_dir(paths.current_root()).expect("create existing index root"); + std::fs::write(paths.daemon_log(), b"sentinel\n").expect("write sentinel daemon log"); + let detail = lockless_missing_detail(&project, &paths); + let project_arg = project.to_str().expect("UTF-8 project path"); + + assert_query_error(&dir, &project, &detail); + + let human = run_in(dir.path(), &["status", project_arg]); + assert!(human.ok, "human status must succeed: {}", human.stderr); + assert_eq!(normalize(&human.stderr), ""); + assert_eq!( + human.stdout, + format!( + "\nCodeGraph Status\n\nProject: {}\nDB Path: {}\nState: missing\nDaemon: stopped\n{detail}\n", + project.display(), + paths.current_db().display() + ) + ); + + let json_run = run_in(dir.path(), &["status", "--json", project_arg]); + assert!(json_run.ok, "JSON status must succeed: {}", json_run.stderr); + assert_eq!(normalize(&json_run.stderr), ""); + let value: serde_json::Value = + serde_json::from_str(json_run.stdout.trim()).expect("status emits JSON"); + assert_eq!(value["initialized"], false); + assert_eq!(value["extractionStatus"], "missing"); + assert_eq!(value["extractionStatusDetail"], detail); + assert_eq!( + value["recoveryCommand"], + format!("codegraph init \"{}\"", project.display()) + ); + assert!(!paths.permanent_lock().exists()); +} + +#[test] +fn lockless_root_recovery_fresh_missing_keeps_original_diagnostics_and_creates_nothing() { + let dir = TestDir::new("lockless-fresh-missing"); + let project = dir.path().join("project"); + std::fs::create_dir(&project).expect("create fresh project"); + let paths = IndexPaths::resolve(&project, None).expect("resolve fresh paths"); + let project_arg = project.to_str().expect("UTF-8 project path"); + let query_error = format!( + "CodeGraph not initialized in {}; run `codegraph init {}` to create or replace the index", + project.display(), + project.display() + ); + + assert_query_error(&dir, &project, &query_error); + assert!(!paths.current_root().exists()); + + let human = run_in(dir.path(), &["status", project_arg]); + assert!( + human.ok, + "fresh human status must succeed: {}", + human.stderr + ); + assert_eq!(normalize(&human.stderr), ""); + assert_eq!( + human.stdout, + format!( + "\nCodeGraph Status\n\nProject: {}\nDB Path: {}\nState: missing\nDaemon: stopped\nNot initialized\nRun \"codegraph init\" to initialize\n", + project.display(), + paths.current_db().display() + ) + ); + assert!(!paths.current_root().exists()); + + let json_run = run_in(dir.path(), &["status", "--json", project_arg]); + assert!( + json_run.ok, + "fresh JSON status must succeed: {}", + json_run.stderr + ); + assert_eq!(normalize(&json_run.stderr), ""); + let value: serde_json::Value = + serde_json::from_str(json_run.stdout.trim()).expect("status emits JSON"); + assert_eq!(value["initialized"], false); + assert_eq!(value["extractionStatus"], "missing"); + assert!(value.get("recoveryCommand").is_none()); + assert!(!paths.current_root().exists()); +} + +#[test] +fn lockless_root_recovery_refuses_present_future_corrupt_and_current_state() { + for status in ["future", "corrupt", "current-no-db"] { + let dir = TestDir::new(&format!("lockless-refuse-{status}")); + let project = dir.path().join("project"); + std::fs::create_dir(&project).expect("create lifecycle project"); + let paths = IndexPaths::resolve(&project, None).expect("resolve lifecycle paths"); + stage_lifecycle_state(&paths, status); + let expected_status = Store::extraction_status(&paths); + let before = slot_bytes(&paths); + std::fs::remove_file(paths.permanent_lock()).expect("remove permanent lock"); + + let init = run_in( + dir.path(), + &["init", project.to_str().expect("UTF-8 project path")], + ); + assert!(!init.ok, "{status} without a lock must refuse init"); + assert_eq!(normalize(&init.stdout), ""); + assert_eq!(final_error_body(&init.stderr), lock_not_found_error(&paths)); + assert_eq!(Store::extraction_status(&paths), expected_status); + assert_eq!(slot_bytes(&paths), before); + assert!(!paths.permanent_lock().exists()); + assert!(!paths.current_db().exists()); + } +} + +#[test] +fn lockless_root_recovery_race_refuses_state_published_before_kernel_lock() { + let dir = TestDir::new("lockless-handle-opened-race"); + let project = dir.path().join("mini"); + copy_tree(&mini_fixture(), &project); + let paths = IndexPaths::resolve(&project, None).expect("resolve race paths"); + std::fs::create_dir(paths.current_root()).expect("create existing index root"); + let sentinel = b"sentinel daemon diagnostic\n"; + std::fs::write(paths.daemon_log(), sentinel).expect("write sentinel daemon log"); + std::fs::write(paths.config_toml(), b"[app]\nname = \"codegraph\"\n") + .expect("write parseable stale config residue"); + + let barrier = LeaseCheckpointBarrier::start(); + let mut command = Command::new(bin()); + command + .current_dir(dir.path()) + .args(["init", project.to_str().expect("UTF-8 project path")]) + .env("CODEGRAPH_HTTP_REGISTRY_DIR", dir.path()) + .env("CODEGRAPH_NO_DAEMON", "1") + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + barrier.configure(&mut command); + let child = ChildGuard(Some(command.spawn().expect("spawn barriered init"))); + + let mut opened = barrier.wait_for_handle_opened(); + let competitor = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false) + .expect("competitor acquires the still-unlocked permanent lock"); + publish_index_state(&paths, &competitor, StatePhase::Building) + .expect("competitor publishes Building"); + let competitor_status = Store::extraction_status(&paths); + let before = slot_bytes(&paths); + drop(competitor); + opened.write_all(b"R").expect("release barriered init"); + + let output = child.finish(); + assert!( + !output.status.success(), + "takeover must reject state published before it acquired the kernel lock: stdout={}, stderr={}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) + ); + assert_eq!(normalize(&String::from_utf8_lossy(&output.stdout)), ""); + assert_eq!( + final_error_body(&String::from_utf8_lossy(&output.stderr)), + format!( + "lockless index takeover at {} no longer classifies missing after acquiring the permanent lock; found {competitor_status}", + paths.current_root().display() + ) + ); + assert_eq!(Store::extraction_status(&paths), competitor_status); + assert_eq!(slot_bytes(&paths), before); + assert!(!paths.current_db().exists()); + assert_eq!( + std::fs::read(paths.daemon_log()).expect("read preserved sentinel"), + sentinel + ); + assert!(paths.permanent_lock().is_file()); +} + #[test] fn nested_status_discovers_authenticated_non_current_parent_states() { for expected in ["building", "outdated", "future", "corrupt"] { diff --git a/crates/codegraph-daemon/src/spawn.rs b/crates/codegraph-daemon/src/spawn.rs index ba6c5ffd..1312e660 100644 --- a/crates/codegraph-daemon/src/spawn.rs +++ b/crates/codegraph-daemon/src/spawn.rs @@ -23,11 +23,12 @@ const DETACHED_PROCESS: u32 = 0x0000_0008; const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200; /// Spawn a detached background daemon by re-invoking `exe serve --mcp --path -/// ` with `CODEGRAPH_DAEMON_INTERNAL=1`, redirecting stdout+stderr to an -/// appended `.codegraph/daemon.log`, detaching it from this process group, and -/// keeping a tiny reaper thread to wait on the child when it exits. The -/// executable path is a parameter so the daemon crate stays testable; the CLI -/// passes `std::env::current_exe()?`. +/// ` with `CODEGRAPH_DAEMON_INTERNAL=1`. When the index root already exists, +/// stdout+stderr append to `.codegraph/daemon.log`; otherwise they use the null +/// sink rather than creating an index namespace solely for logging. The child is +/// detached from this process group and a tiny reaper thread waits for its exit. +/// The executable path is a parameter so the daemon crate stays testable; the +/// CLI passes `std::env::current_exe()?`. /// /// `no_watch` forwards the `--no-watch` intent to the detached child EXPLICITLY /// via `Command.env` instead of mutating this process's global environment. @@ -63,13 +64,12 @@ pub fn spawn_detached_daemon(exe: &Path, root: &Path, no_watch: bool) -> Result< Ok(()) } -/// The rendezvous dir is created by the daemon's lock layer in the CHILD, but -/// this log redirect is set up in the PARENT before spawn, so the parent creates -/// the log's parent directory here — otherwise the redirect silently falls back -/// to a null sink and the child's stderr is lost. +/// Open a project-local append target only when its parent is already a directory. +/// Falling back to the null sink keeps a failed background start from creating a +/// lockless index root merely to hold diagnostics. fn log_target(path: &Path) -> Stdio { - if let Some(parent) = path.parent() { - let _ = std::fs::create_dir_all(parent); + if !path.parent().is_some_and(Path::is_dir) { + return Stdio::null(); } OpenOptions::new() .create(true) @@ -229,6 +229,46 @@ mod tests { let _ = fs::remove_dir_all(root); } + #[test] + fn lockless_root_recovery_spawn_does_not_create_absent_index_root() { + let exe = Path::new("/bin/true"); + assert!(exe.exists(), "/bin/true is required for this Unix test"); + let project = temp_root("lockless-absent-root"); + let log = crate::paths::daemon_log_path(&project).expect("resolve daemon log"); + let index_root = log.parent().expect("daemon log has an index root"); + assert!(!index_root.exists()); + + spawn_detached_daemon(exe, &project, false).expect("spawn short-lived daemon command"); + + assert!(project.is_dir()); + assert!(!index_root.exists()); + assert!(!log.exists()); + assert!( + eventually_no_zombie_children(Duration::from_secs(1)), + "spawn_detached_daemon must reap the absent-root control child" + ); + let _ = fs::remove_dir_all(project); + } + + #[test] + fn lockless_root_recovery_spawn_keeps_existing_index_root_log() { + let exe = Path::new("/bin/true"); + assert!(exe.exists(), "/bin/true is required for this Unix test"); + let project = temp_root("lockless-existing-root"); + let log = crate::paths::daemon_log_path(&project).expect("resolve daemon log"); + let index_root = log.parent().expect("daemon log has an index root"); + fs::create_dir(index_root).expect("create existing index root"); + + spawn_detached_daemon(exe, &project, false).expect("spawn short-lived daemon command"); + + assert!(fs::metadata(&log).is_ok_and(|metadata| metadata.is_file())); + assert!( + eventually_no_zombie_children(Duration::from_secs(1)), + "spawn_detached_daemon must reap the existing-root control child" + ); + let _ = fs::remove_dir_all(project); + } + #[test] fn spawn_detached_http_returns_pid_and_reaps_child() { let exe = Path::new("/bin/true"); diff --git a/crates/codegraph-store/src/index_lease.rs b/crates/codegraph-store/src/index_lease.rs index 9ad6464c..d26c0f53 100644 --- a/crates/codegraph-store/src/index_lease.rs +++ b/crates/codegraph-store/src/index_lease.rs @@ -72,8 +72,11 @@ pub struct IndexLease { /// Typed failures while opening or acquiring a permanent index lock. #[derive(Debug, Error)] pub enum IndexLeaseError { - /// An existing namespace has no permanent lock. - #[error("permanent index lock does not exist: {path}")] + /// An existing namespace has no permanent lock; state must be classified + /// before deciding whether explicit init is safe. + #[error( + "existing index namespace has no permanent lock file at {path}; a failed background daemon start can leave this stale shape. Run `codegraph status` from the project root to classify it; only `State: missing` is safe to recover with `codegraph init`." + )] LockNotFound { path: PathBuf }, /// The fixed permanent-lock path is a symlink or Windows reparse point. #[error("permanent index lock is an alias and cannot be lock authority: {path}")] @@ -189,8 +192,10 @@ impl IndexLease { } /// Create and acquire the permanent lock inside an existing, state-less - /// namespace selected for stale-cache replacement. Callers must classify the - /// namespace again under the returned lease before changing any other byte. + /// namespace selected for stale-cache replacement. Callers must classify + /// before attempting creation, then re-classify under the genuinely held + /// returned lease before authorizing or changing any other byte: creating the + /// lock file is not itself possession of its kernel lock. pub(crate) fn create_exclusive_in_existing_root( paths: &IndexPaths, deadline: Instant, @@ -226,6 +231,8 @@ impl IndexLease { .open(&lock_path) .map_err(|source| classify_create_error(&lock_path, source))?; let opened_identity = opened_identity(&file, &lock_path, None)?; + #[cfg(feature = "test-hooks")] + lease_test_checkpoint(AcquireCheckpoint::HandleOpened); Self::acquire_file( file, PendingAcquisition { @@ -481,18 +488,17 @@ impl IndexLease { } } -/// Deterministic cross-process checkpoint used only by integration-test builds. +/// Deterministic cross-process barriers used only by integration-test builds. /// -/// A test child opts in by supplying a loopback listener address and the lease -/// mode it wants to stop. The hook writes one acknowledged mode byte only after -/// the kernel lock and final path corroboration both succeeded, then waits for a -/// release byte with bounded socket timeouts. No corresponding strings or I/O -/// path are compiled into normal/release builds. +/// The existing mode selector writes `S` or `X` only after the kernel lock and +/// final-path corroboration both succeed. The checkpoint selector can separately +/// stop existing-root lock creation at `HandleOpened`, writing `H` before the +/// first kernel-lock attempt. Both protocols wait for one `R` release byte with +/// bounded socket timeouts. No corresponding strings or I/O path are compiled +/// into normal/release builds. #[cfg(feature = "test-hooks")] fn lease_test_barrier(mode: LeaseMode) { - const ADDR_ENV: &str = "CODEGRAPH_TEST_LEASE_BARRIER_ADDR"; const MODE_ENV: &str = "CODEGRAPH_TEST_LEASE_BARRIER_MODE"; - const WAIT: Duration = Duration::from_secs(10); let expected = match std::env::var(MODE_ENV) { Ok(value) => value, @@ -505,8 +511,28 @@ fn lease_test_barrier(mode: LeaseMode) { if expected != mode_name { return; } + lease_test_wait(marker, MODE_ENV); +} + +#[cfg(feature = "test-hooks")] +fn lease_test_checkpoint(checkpoint: AcquireCheckpoint) { + const CHECKPOINT_ENV: &str = "CODEGRAPH_TEST_LEASE_BARRIER_CHECKPOINT"; + + if checkpoint != AcquireCheckpoint::HandleOpened + || !matches!(std::env::var(CHECKPOINT_ENV), Ok(value) if value == "handle-opened") + { + return; + } + lease_test_wait(b'H', CHECKPOINT_ENV); +} + +#[cfg(feature = "test-hooks")] +fn lease_test_wait(marker: u8, selector_env: &str) { + const ADDR_ENV: &str = "CODEGRAPH_TEST_LEASE_BARRIER_ADDR"; + const WAIT: Duration = Duration::from_secs(10); + let address = std::env::var(ADDR_ENV) - .unwrap_or_else(|_| panic!("{MODE_ENV} requires {ADDR_ENV}")) + .unwrap_or_else(|_| panic!("{selector_env} requires {ADDR_ENV}")) .parse() .unwrap_or_else(|error| panic!("invalid {ADDR_ENV}: {error}")); let mut stream = std::net::TcpStream::connect_timeout(&address, WAIT) @@ -831,4 +857,17 @@ mod tests { .expect("failed creation never locks the competing entry"); competing_handle.unlock().expect("unlock competing entry"); } + + #[test] + fn lockless_root_recovery_lock_not_found_is_actionable() { + let path = PathBuf::from("/tmp/project/.codegraph/index.lock"); + let error = IndexLeaseError::LockNotFound { path: path.clone() }; + assert_eq!( + error.to_string(), + format!( + "existing index namespace has no permanent lock file at {}; a failed background daemon start can leave this stale shape. Run `codegraph status` from the project root to classify it; only `State: missing` is safe to recover with `codegraph init`.", + path.display() + ) + ); + } } diff --git a/crates/codegraph-store/src/rebuild.rs b/crates/codegraph-store/src/rebuild.rs index 74bee657..160dec4a 100644 --- a/crates/codegraph-store/src/rebuild.rs +++ b/crates/codegraph-store/src/rebuild.rs @@ -137,6 +137,16 @@ pub enum RebuildError { /// Operating-system error. source: io::Error, }, + /// A lockless namespace stopped classifying Missing before takeover held its lock. + #[error( + "lockless index takeover at {path} no longer classifies missing after acquiring the permanent lock; found {status}" + )] + LocklessTakeoverStateChanged { + /// Resolved current root. + path: PathBuf, + /// Classification observed while holding the newly created permanent lock. + status: crate::ExtractionStatus, + }, /// A database artifact could not be removed under the lease. #[error("cannot remove database artifact {path}: {source}")] RemoveDatabase { @@ -735,6 +745,11 @@ fn checkpoint( }) } +/// Acquire the one outer exclusive lease for a rebuild. A lockless existing +/// root is eligible for permanent-lock creation only after a Missing precheck; +/// because creating the file does not yet possess its kernel lock, the recovery +/// arm re-asserts Missing while holding the returned lease before authorizing +/// any state publication or database mutation. fn acquire_outer_exclusive( paths: &IndexPaths, deadline: Instant, @@ -744,29 +759,26 @@ fn acquire_outer_exclusive( match IndexLease::acquire_or_create_exclusive(paths, deadline, &mut cancelled) { Ok(lease) => Ok(lease), Err(IndexLeaseError::LockNotFound { .. }) - if Store::extraction_status(paths) == crate::ExtractionStatus::Missing - && (first_existing_database_artifact(paths)?.is_some() - || first_existing_project_config(paths)?.is_some()) => + if Store::extraction_status(paths) == crate::ExtractionStatus::Missing => { - Ok(IndexLease::create_exclusive_in_existing_root( - paths, deadline, cancelled, - )?) + let lease = IndexLease::create_exclusive_in_existing_root(paths, deadline, cancelled)?; + let status = Store::extraction_status(paths); + if status != crate::ExtractionStatus::Missing { + return Err(RebuildError::LocklessTakeoverStateChanged { + path: paths + .permanent_lock() + .parent() + .expect("the permanent lock always belongs to the current index root") + .to_path_buf(), + status, + }); + } + Ok(lease) } Err(error) => Err(error.into()), } } -fn first_existing_project_config(paths: &IndexPaths) -> Result, RebuildError> { - for path in [paths.config_toml(), paths.extension_config()] { - match std::fs::symlink_metadata(&path) { - Ok(_) => return Ok(Some(path)), - Err(error) if error.kind() == io::ErrorKind::NotFound => {} - Err(source) => return Err(RebuildError::InspectRoot { path, source }), - } - } - Ok(None) -} - fn remove_database_files(paths: &IndexPaths, lease: &IndexLease) -> Result<(), RebuildError> { let db = paths.current_db(); for path in [ @@ -1761,25 +1773,28 @@ mod tests { } #[test] - fn existing_root_without_a_permanent_lock_fails_closed() { + fn missing_existing_root_without_a_permanent_lock_begins_rebuild_safely() { let project = TempProject::new("lockless"); let paths = project.paths(); std::fs::create_dir_all(paths.current_root()).expect("stage a lockless root"); - let error = begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false) - .expect_err("a lockless existing namespace must never be repaired"); + let rebuild = begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false) + .expect("a Missing lockless namespace may begin explicit init"); assert!( - matches!( - error, - RebuildError::Lease(IndexLeaseError::LockNotFound { .. }) - ), - "unexpected error: {error}" + paths.permanent_lock().is_file(), + "takeover must create the permanent lock without replacing the root" + ); + assert_eq!( + Store::extraction_status(&paths), + ExtractionStatus::Building { + built: crate::CURRENT_EXTRACTION_VERSION, + } ); - assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Missing); assert!( !paths.current_db().exists(), - "a refused rebuild must not create a database" + "the authorized prologue must not open SQLite before open_store" ); + drop(rebuild); } /// Take the incremental-sync authorization the way a real sync does: ONE