use parking_lot::Mutex;
use std::sync::Arc;
use crate::live_index::persist;
use crate::{
cli, daemon, discovery, live_index, observability, protocol, server, sidecar, version_registry,
watcher,
};
use clap::Parser;
use rmcp::{serve_server, transport};
use std::ffi::OsString;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MainExit {
Success,
ServeRefusedToStart,
}
pub fn run_main(args: Vec<OsString>) -> anyhow::Result<MainExit> {
version_registry::record_self_default();
if cli::version::is_version_request(&args) {
return cli::version::run_version().map(|()| MainExit::Success);
}
let cli = cli::Cli::parse_from(args);
let completed = match cli.command {
Some(cli::Commands::Analytics { command }) => cli::analytics::run_analytics(&command),
Some(cli::Commands::Init {
client,
scan,
apply,
serve_url,
serve_key,
}) => {
if scan {
cli::init::run_scan(apply, serve_url, serve_key)
} else {
cli::init::run_init(client)
}
}
Some(cli::Commands::Daemon) => run_daemon(),
Some(cli::Commands::Serve(args)) => return run_serve(args),
Some(cli::Commands::Setup(args)) => cli::setup::run(args),
Some(cli::Commands::Admin(args)) => cli::admin::run(args),
Some(cli::Commands::Hook { subcommand }) => cli::hook::run_hook(subcommand.as_ref()),
Some(cli::Commands::Trust { subcommand }) => cli::trust::run_trust(&subcommand),
Some(cli::Commands::Update) => cli::update::run_update(),
None => run_mcp_server(),
};
completed.map(|()| MainExit::Success)
}
#[derive(Debug, Clone, PartialEq, Eq)]
enum StartupPlan {
Daemon { root: std::path::PathBuf },
LocalAutoIndex { root: std::path::PathBuf },
LocalEmpty { reason: String },
}
#[derive(Debug, Clone, PartialEq, Eq)]
enum StartupIndexLogView {
Ready {
file_count: usize,
symbol_count: usize,
parsed_count: usize,
partial_parse_count: usize,
failed_count: usize,
duration_ms: u64,
},
Degraded {
summary: String,
},
}
fn startup_index_log_view(
published: &live_index::PublishedIndexState,
) -> Option<StartupIndexLogView> {
match published.status {
live_index::PublishedIndexStatus::Ready => Some(StartupIndexLogView::Ready {
file_count: published.file_count,
symbol_count: published.symbol_count,
parsed_count: published.parsed_count,
partial_parse_count: published.partial_parse_count,
failed_count: published.failed_count,
duration_ms: published.load_duration.as_millis() as u64,
}),
live_index::PublishedIndexStatus::Degraded => Some(StartupIndexLogView::Degraded {
summary: published
.degraded_summary
.clone()
.unwrap_or_else(|| "circuit breaker tripped".to_string()),
}),
live_index::PublishedIndexStatus::Empty | live_index::PublishedIndexStatus::Loading => None,
}
}
fn local_empty_reason(should_auto_index: bool) -> &'static str {
if !should_auto_index {
"SYMFORGE_AUTO_INDEX=false — starting with empty index"
} else {
"no safe project root found — starting with empty index"
}
}
fn startup_plan(
should_auto_index: bool,
resolved_root: Option<std::path::PathBuf>,
daemon_available: bool,
) -> StartupPlan {
match (resolved_root, daemon_available) {
(Some(root), true) => StartupPlan::Daemon { root },
(Some(root), false) => StartupPlan::LocalAutoIndex { root },
(None, _) => StartupPlan::LocalEmpty {
reason: local_empty_reason(should_auto_index).to_string(),
},
}
}
fn spawn_periodic_checkpoint(
index: live_index::SharedIndex,
root: std::path::PathBuf,
state_placement: crate::domain::StatePlacement,
interval: std::time::Duration,
) -> tokio::task::JoinHandle<()> {
tokio::spawn(async move {
loop {
tokio::time::sleep(interval).await;
let checkpoint_index = Arc::clone(&index);
let checkpoint_root = root.clone();
let checkpoint_placement = state_placement.clone();
match tokio::task::spawn_blocking(move || {
persist::checkpoint_shared_index(
&checkpoint_index,
&checkpoint_root,
&checkpoint_placement,
)
})
.await
{
Ok(Ok(report)) => tracing::info!(
bytes = report.bytes,
files = report.files,
path = %report.path.display(),
"periodic checkpoint wrote .symforge/index.bin"
),
Ok(Err(error)) => tracing::warn!(
interval_secs = interval.as_secs(),
"periodic checkpoint failed: {error}"
),
Err(join_error) => tracing::warn!(
interval_secs = interval.as_secs(),
"periodic checkpoint task panicked: {join_error}"
),
}
}
})
}
fn run_daemon() -> anyhow::Result<()> {
tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()?
.block_on(async {
observability::init_tracing()?;
daemon::run_daemon_until_shutdown("127.0.0.1").await
})
}
fn run_serve(args: cli::serve::ServeCliArgs) -> anyhow::Result<MainExit> {
let runtime = tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()?;
let result = runtime.block_on(async {
observability::init_tracing()?;
Ok::<Result<(), server::serve::ServeError>, anyhow::Error>(
server::serve::run(args.into_serve_args()).await,
)
})?;
match result {
Ok(()) => Ok(MainExit::Success),
Err(server::serve::ServeError::Startup(err)) => {
eprintln!("error: {err}");
Ok(MainExit::ServeRefusedToStart)
}
Err(other) => Err(anyhow::Error::from(other)),
}
}
fn run_mcp_server() -> anyhow::Result<()> {
tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()?
.block_on(async { run_mcp_server_async().await })
}
async fn run_mcp_server_async() -> anyhow::Result<()> {
observability::init_tracing()?;
live_index::index_lifecycle::activation::activate_surface(
live_index::index_lifecycle::process_runtime::SurfaceKind::Stdio,
);
let should_auto_index = std::env::var("SYMFORGE_AUTO_INDEX")
.map(|v| v != "false")
.unwrap_or(true);
let resolved_root = if should_auto_index {
discovery::find_project_root()
} else {
None
};
let use_daemon = std::env::var("SYMFORGE_NO_DAEMON")
.map(|v| v == "0" || v.is_empty())
.unwrap_or(true);
match startup_plan(should_auto_index, resolved_root, use_daemon) {
StartupPlan::Daemon { root } => {
run_deferred_mcp_server_async(root, true, should_auto_index).await
}
StartupPlan::LocalAutoIndex { root } => {
run_deferred_mcp_server_async(root, false, should_auto_index).await
}
StartupPlan::LocalEmpty { .. } => {
run_local_mcp_server_async(should_auto_index, None, StdioServe::Direct).await
}
}
}
enum StdioServe {
Direct,
Deferred {
startup: Arc<tokio::sync::watch::Sender<protocol::deferred_stdio::StdioStartup>>,
shutdown: tokio::sync::watch::Receiver<bool>,
},
}
async fn serve_stdio(server: protocol::SymForgeServer, serve: StdioServe) -> anyhow::Result<()> {
match serve {
StdioServe::Direct => {
let service = serve_server(server, transport::stdio()).await?;
tokio::select! {
result = service.waiting() => { result?; }
_ = tokio::signal::ctrl_c() => {
tracing::info!("Ctrl+C received, shutting down");
}
}
}
StdioServe::Deferred {
startup,
mut shutdown,
} => {
startup.send_replace(protocol::deferred_stdio::StdioStartup::Ready(Arc::new(
server,
)));
let _ = shutdown.wait_for(|stop| *stop).await;
}
}
Ok(())
}
async fn run_deferred_mcp_server_async(
root: std::path::PathBuf,
use_daemon: bool,
should_auto_index: bool,
) -> anyhow::Result<()> {
let (front, startup) = protocol::deferred_stdio::DeferredStdioServer::new(&root);
let publish = Arc::new(startup);
let (shutdown, shutdown_signal) = tokio::sync::watch::channel(false);
let runtime = tokio::spawn(async move {
let _unpublished =
protocol::deferred_stdio::StartupGuard(Arc::clone(&publish), shutdown_signal.clone());
let mut client_left = shutdown_signal.clone();
let serve = StdioServe::Deferred {
startup: Arc::clone(&publish),
shutdown: shutdown_signal,
};
let result = if use_daemon {
let connected = tokio::select! {
connected = daemon::connect_or_spawn_session(
&root,
"mcp-stdio",
Some(std::process::id()),
) => connected,
_ = client_left.wait_for(|stop| *stop) => return Ok(()),
};
match connected {
Ok(session) => {
daemon::run_then_close_session(session.clone(), async |slot| {
run_remote_mcp_server_async(session, serve, slot).await
})
.await
}
Err(error) => {
tracing::warn!(
root = %root.display(),
"daemon-backed startup failed, falling back to local mode: {error}"
);
run_local_mcp_server_async(should_auto_index, Some(root), serve).await
}
}
} else {
run_local_mcp_server_async(should_auto_index, Some(root), serve).await
};
if let Err(error) = &result {
publish.send_if_modified(|state| {
let starting = matches!(state, protocol::deferred_stdio::StdioStartup::Starting);
if starting {
*state =
protocol::deferred_stdio::StdioStartup::Failed(format!("{error:#}").into());
}
starting
});
}
result
});
tracing::info!("serving MCP on stdio while the project runtime starts");
let service = match serve_server(front, transport::stdio()).await {
Ok(service) => service,
Err(error) => {
let _ = shutdown.send(true);
let _ = runtime.await;
return Err(error.into());
}
};
let served = tokio::select! {
result = service.waiting() => result.map(|_| ()).map_err(anyhow::Error::from),
_ = tokio::signal::ctrl_c() => {
tracing::info!("Ctrl+C received, shutting down");
Ok(())
}
};
let _ = shutdown.send(true);
let runtime = runtime.await;
served?;
runtime?
}
async fn run_remote_mcp_server_async(
session: daemon::DaemonSessionClient,
serve: StdioServe,
current_session: &mut Option<daemon::SessionSlot>,
) -> anyhow::Result<()> {
let control_state_dir = crate::paths::process_control_state_placement()
.directory()
.cloned();
if let (Some(port), Some(state_dir)) = (session.port(), control_state_dir.as_ref()) {
sidecar::port_file::write_session_descriptor(
state_dir,
port,
Some(session.session_id()),
session.project_root(),
session.daemon_started_at(),
)?;
}
let state_placement = session.project_root().and_then(|root| {
match discovery::resolve_root_candidate(
root,
crate::domain::RootCandidateSource::LaunchCwd,
crate::domain::RootRequestMode::Automatic,
) {
crate::domain::RootResolution::Bound(binding) => {
Some(discovery::resolve_state_placement(&binding))
}
crate::domain::RootResolution::Unbound { .. } => None,
}
});
let project_state_dir = state_placement
.as_ref()
.and_then(|placement| placement.directory())
.cloned();
let mut server = protocol::SymForgeServer::new_daemon_proxy_with_state_placement(
session.clone(),
state_placement,
);
if let Some(state_dir) = control_state_dir.as_ref() {
server.set_descriptor_state_dir(state_dir.clone());
}
let heartbeat_slot = server.daemon_client_slot();
*current_session = heartbeat_slot.clone();
let heartbeat_task = tokio::spawn(async move {
loop {
tokio::time::sleep(std::time::Duration::from_secs(15)).await;
let Some(slot) = heartbeat_slot.as_ref() else {
continue;
};
let current = slot.read().await.clone();
let _ = current.heartbeat().await;
}
});
if let Some(state_dir) = project_state_dir.as_ref() {
let store = crate::stel::ledger_store::StelLedgerStore::open(
state_dir,
format!("stdio-daemon-{}", std::process::id()),
);
server = server.with_stel_ledger_store(Arc::new(store));
}
tracing::info!(
project_id = %session.project_id(),
session_id = %session.session_id(),
"starting daemon-backed MCP server on stdio transport"
);
let served = serve_stdio(server.with_stdio_transport_lane(), serve).await;
heartbeat_task.abort();
if let Some(state_dir) = control_state_dir.as_ref() {
sidecar::port_file::cleanup_own_descriptor(state_dir);
}
served?;
tracing::info!("daemon-backed MCP server shut down cleanly");
Ok(())
}
fn spawn_local_cold_load(
index: live_index::SharedIndex,
root: std::path::PathBuf,
placement: crate::domain::StatePlacement,
) -> tokio::task::JoinHandle<()> {
index.arm_deferred_cold_knowledge();
tokio::task::spawn_blocking(move || {
tracing::info!("cold-start indexing in background");
let result =
daemon::load_catching_panic(|| index.reload_for_state_placement(&root, &placement));
if daemon::settle_background_cold_load(&index, &root, result) {
tracing::info!("background cold-start indexing complete");
}
})
}
async fn run_local_mcp_server_async(
should_auto_index: bool,
resolved_root: Option<std::path::PathBuf>,
serve: StdioServe,
) -> anyhow::Result<()> {
let (index, project_name, watcher_root, state_placement) = if let Some(root) = resolved_root {
tracing::info!(root = %root.display(), "auto-indexing from project root");
let binding = match discovery::resolve_root_candidate(
&root,
crate::domain::RootCandidateSource::LaunchCwd,
crate::domain::RootRequestMode::Automatic,
) {
crate::domain::RootResolution::Bound(binding) => binding,
resolution => anyhow::bail!(
"resolved local project root no longer satisfies the canonical source guard: {resolution:?}"
),
};
let state_placement = discovery::resolve_state_placement(&binding);
let admission = live_index::index_lifecycle::activation::admit_project(
live_index::index_lifecycle::process_runtime::SurfaceKind::Stdio,
&binding.canonical_root,
&binding.root_id.0,
binding.access_mode,
&state_placement,
)
.map_err(|refusal| {
anyhow::anyhow!(
"project admission refused for '{}': {refusal:?}",
binding.root_id.0
)
})?;
let source_authority =
live_index::index_lifecycle::activation::project_source_authority(&root);
let admitted_physical_root = admission
.binding()
.map_err(|refusal| anyhow::anyhow!("project admission retired: {refusal:?}"))?
.physical_root();
if source_authority.admission_binding().physical_root() != admitted_physical_root {
anyhow::bail!("admitted local source changed before snapshot restore");
}
let index = if let Some(snapshot) =
persist::load_snapshot_bound(&root, &state_placement, &source_authority)
.map_err(|refusal| anyhow::anyhow!("admitted snapshot load refused: {refusal:?}"))?
{
let file_count = snapshot.files.len();
let snapshot_mtimes: std::collections::HashMap<String, u64> = snapshot
.files
.iter()
.map(|(k, v)| (k.clone(), v.mtime_secs))
.collect();
let (live, code_signals) = persist::snapshot_to_live_index_with_code_signals_bound(
snapshot,
&root,
&source_authority,
)
.map_err(|refusal| anyhow::anyhow!("admitted snapshot source refused: {refusal:?}"))?;
tracing::info!(
files = file_count,
load_source = ?live.load_source(),
snapshot_verify_state = ?live.snapshot_verify_state(),
"loaded serialized index from .symforge/index.bin"
);
let shared: live_index::SharedIndex =
live_index::SharedIndexHandle::shared_restored_for_state_placement_with_code_signals(
live,
&root,
&state_placement,
code_signals,
);
let bg_index = shared.clone();
let bg_root = root.clone();
let bg_authority = source_authority.clone();
tokio::spawn(async move {
persist::background_verify_cancellable_bound(
bg_index,
bg_root,
snapshot_mtimes,
bg_authority,
|| false,
)
.await;
});
shared
} else {
let shared = live_index::LiveIndex::empty();
shared.mark_bootstrap_loading();
spawn_local_cold_load(shared.clone(), root.clone(), state_placement.clone());
shared
};
let published = index.published_state();
match startup_index_log_view(&published) {
Some(StartupIndexLogView::Ready {
file_count,
symbol_count,
parsed_count,
partial_parse_count,
failed_count,
duration_ms,
}) => {
tracing::info!(
files = file_count,
symbols = symbol_count,
parsed = parsed_count,
partial = partial_parse_count,
failed = failed_count,
duration_ms,
"LiveIndex ready"
);
}
Some(StartupIndexLogView::Degraded { summary }) => {
tracing::error!(%summary, "circuit breaker tripped — index degraded");
}
None => {}
}
let name = root
.file_name()
.and_then(|n| n.to_str())
.unwrap_or("project")
.to_string();
(index, name, Some(root), Some(state_placement))
} else {
tracing::info!("{}", local_empty_reason(should_auto_index));
let live = live_index::LiveIndex::empty();
live.set_local_empty_reason(Some(local_empty_reason(should_auto_index).to_string()));
(live, "project".to_string(), None, None)
};
let watcher_info = Arc::new(Mutex::new(watcher::WatcherInfo::default()));
if let Some(ref root) = watcher_root {
let watcher_index = Arc::clone(&index);
let watcher_root_clone = root.clone();
let watcher_info_clone = Arc::clone(&watcher_info);
tokio::spawn(async move {
watcher::run_watcher(watcher_root_clone, watcher_index, watcher_info_clone).await;
});
tracing::info!("file watcher started");
}
if let Some(ref root) = watcher_root {
let expected_gen = index.current_project_generation();
live_index::git_temporal::spawn_git_temporal_computation(
Arc::clone(&index),
root.clone(),
expected_gen,
);
}
let periodic_checkpoint = watcher_root
.as_ref()
.zip(state_placement.as_ref())
.and_then(|(root, placement)| {
persist::checkpoint_interval_from_env().map(|interval| {
tracing::info!(
interval_secs = interval.as_secs(),
env = persist::CHECKPOINT_INTERVAL_ENV,
"periodic checkpointing enabled"
);
spawn_periodic_checkpoint(
Arc::clone(&index),
root.clone(),
placement.clone(),
interval,
)
})
});
let bind_host =
std::env::var("SYMFORGE_SIDECAR_BIND").unwrap_or_else(|_| "127.0.0.1".to_string());
let control_state_dir = crate::paths::process_control_state_placement()
.directory()
.cloned();
let sidecar_handle = sidecar::spawn_sidecar(
Arc::clone(&index),
&bind_host,
watcher_root.clone(),
control_state_dir,
)
.await?;
tracing::info!(port = sidecar_handle.port, "HTTP sidecar started");
let token_stats = Some(Arc::clone(&sidecar_handle.token_stats));
let mut server = protocol::SymForgeServer::new_with_state_placement(
Arc::clone(&index),
project_name,
watcher_info,
watcher_root.clone(),
state_placement.clone(),
token_stats,
);
if let Some(state_dir) = state_placement
.as_ref()
.and_then(|placement| placement.directory())
{
let store = crate::stel::ledger_store::StelLedgerStore::open(
state_dir,
format!("stdio-{}", std::process::id()),
);
server = server.with_stel_ledger_store(Arc::new(store));
}
tracing::info!("starting MCP server on stdio transport");
serve_stdio(server.with_stdio_transport_lane(), serve).await?;
tracing::info!("MCP server shut down cleanly");
if let Some(handle) = periodic_checkpoint {
handle.abort();
}
if let (Some(root), Some(placement)) = (watcher_root.as_ref(), state_placement.as_ref()) {
match persist::serialize_shared_index(&index, root, placement) {
Ok(()) => tracing::info!("index serialized to .symforge/index.bin"),
Err(e) => tracing::warn!("failed to serialize index on shutdown: {e}"),
}
}
sidecar_handle.shutdown_and_join().await;
tracing::info!("sidecar shutdown complete");
Ok(())
}
#[cfg(test)]
mod tests {
use super::{
StartupIndexLogView, StartupPlan, local_empty_reason, spawn_local_cold_load,
startup_index_log_view, startup_plan,
};
use crate::live_index::persist::checkpoint_interval_from_value;
use crate::live_index::{
IndexLoadSource, PublishedIndexState, PublishedIndexStatus, SnapshotVerifyState,
};
use std::path::PathBuf;
use std::time::{Duration, SystemTime};
fn published_state(status: PublishedIndexStatus) -> PublishedIndexState {
PublishedIndexState {
generation: 7,
status,
degraded_summary: None,
file_count: 12,
parsed_count: 10,
partial_parse_count: 1,
unexpected_partial_parse_count: 1,
expected_vendor_partial_parse_count: 0,
expected_generated_partial_parse_count: 0,
expected_test_fixture_partial_parse_count: 0,
expected_template_dsl_partial_parse_count: 0,
expected_framework_partial_parse_count: 0,
expected_language_partial_parse_count: 0,
failed_count: 1,
partial_parse_files: vec!["src/partial.rs".to_string()],
unexpected_partial_parse_files: vec!["src/partial.rs".to_string()],
expected_vendor_partial_parse_files: vec![],
expected_generated_partial_parse_files: vec![],
expected_test_fixture_partial_parse_files: vec![],
expected_template_dsl_partial_parse_files: vec![],
expected_framework_partial_parse_files: vec![],
expected_language_partial_parse_files: vec![],
failed_files: vec![("src/failed.rs".to_string(), "syntax error".to_string())],
symbol_count: 34,
loaded_at_system: SystemTime::now(),
load_duration: Duration::from_millis(42),
load_source: IndexLoadSource::FreshLoad,
snapshot_verify_state: SnapshotVerifyState::NotNeeded,
is_empty: false,
tier_counts: (0, 0, 0),
local_empty_reason: None,
untracked_indexed: 0,
indexed_root: None,
}
}
#[test]
fn test_startup_index_log_view_uses_published_ready_counts() {
let published = published_state(PublishedIndexStatus::Ready);
assert_eq!(
startup_index_log_view(&published),
Some(StartupIndexLogView::Ready {
file_count: 12,
symbol_count: 34,
parsed_count: 10,
partial_parse_count: 1,
failed_count: 1,
duration_ms: 42,
})
);
}
#[test]
fn test_startup_index_log_view_uses_published_degraded_summary() {
let mut published = published_state(PublishedIndexStatus::Degraded);
published.degraded_summary = Some("circuit breaker tripped: 3/10 files failed".to_string());
assert_eq!(
startup_index_log_view(&published),
Some(StartupIndexLogView::Degraded {
summary: "circuit breaker tripped: 3/10 files failed".to_string(),
})
);
}
#[test]
fn test_startup_plan_prefers_daemon_when_root_exists() {
let root = PathBuf::from("repo");
assert_eq!(
startup_plan(true, Some(root.clone()), true),
StartupPlan::Daemon { root }
);
}
#[test]
fn test_startup_plan_falls_back_to_local_auto_index_when_daemon_unavailable() {
let root = PathBuf::from("repo");
assert_eq!(
startup_plan(true, Some(root.clone()), false),
StartupPlan::LocalAutoIndex { root }
);
}
#[test]
fn test_startup_plan_reports_disabled_auto_index_reason() {
assert_eq!(
startup_plan(false, None, false),
StartupPlan::LocalEmpty {
reason: local_empty_reason(false).to_string(),
}
);
}
#[test]
fn test_startup_plan_reports_missing_root_reason() {
assert_eq!(
startup_plan(true, None, false),
StartupPlan::LocalEmpty {
reason: local_empty_reason(true).to_string(),
}
);
}
#[test]
fn test_checkpoint_interval_is_opt_in_and_bounded() {
assert_eq!(checkpoint_interval_from_value(None), None);
assert_eq!(checkpoint_interval_from_value(Some("0")), None);
assert_eq!(checkpoint_interval_from_value(Some("false")), None);
assert_eq!(
checkpoint_interval_from_value(Some("15")),
Some(Duration::from_secs(30))
);
assert_eq!(
checkpoint_interval_from_value(Some("120")),
Some(Duration::from_secs(120))
);
assert_eq!(
checkpoint_interval_from_value(Some("999999")),
Some(Duration::from_secs(3600))
);
}
#[tokio::test(flavor = "multi_thread")]
async fn a_failed_local_cold_start_does_not_stay_loading() {
let tmp = tempfile::TempDir::new().expect("tempdir");
let missing = tmp.path().join("removed-before-the-load");
let index = crate::live_index::LiveIndex::empty();
index.mark_bootstrap_loading();
assert_eq!(
index.published_state().status,
PublishedIndexStatus::Loading
);
spawn_local_cold_load(
index.clone(),
missing,
crate::domain::StatePlacement::MemoryOnly {
failures: Vec::new(),
},
)
.await
.expect("the load task finished");
let published = index.published_state();
assert_eq!(published.status, PublishedIndexStatus::Empty);
assert!(
published
.local_empty_reason
.as_deref()
.is_some_and(|reason| reason.contains("background index load failed")),
"{:?}",
published.local_empty_reason
);
}
}