byteor_edgeplane/

main.rs

use std::path::PathBuf;
use std::sync::{atomic::AtomicBool, atomic::Ordering, Arc};
use std::thread::{self, JoinHandle};
use std::time::Duration;

fn report_adapter_snapshot(
    reporter: Option<&byteor_app_kit::agent::RuntimeReporter>,
    stats: &byteor_adapters::AdapterLoopStats,
    error: Option<String>,
) {
    let Some(reporter) = reporter else {
        return;
    };

    if let Err(report_error) = reporter.report_snapshot_now("single_ring", || {
        Ok(adapter_snapshot_payload(stats, error.clone()))
    }) {
        eprintln!("agent snapshot failed: {report_error}");
    }
    if let Err(report_error) = reporter.report_heartbeat_now() {
        eprintln!("agent heartbeat failed: {report_error}");
    }
}

fn adapter_snapshot_payload(
    stats: &byteor_adapters::AdapterLoopStats,
    error: Option<String>,
) -> serde_json::Value {
    let mut snapshot = serde_json::json!({
        "mode": "adapter_loop",
        "ok": error.is_none(),
        "ingress_messages": stats.ingress_messages,
        "egress_messages": stats.egress_messages,
    });
    if let Some(error) = error {
        snapshot["error"] = serde_json::json!(error);
    }
    stats.merge_into_snapshot(&mut snapshot);
    snapshot
}

fn idle_adapter_snapshot_payload(
    ingress_name: &str,
    ingress_transport: &str,
    egress_name: &str,
    egress_transport: &str,
) -> serde_json::Value {
    serde_json::json!({
        "mode": "adapter_loop",
        "ok": true,
        "ingress_messages": 0,
        "egress_messages": 0,
        "adapters": [
            {
                "name": ingress_name,
                "role": "ingress",
                "transport": ingress_transport,
                "connection_state": "ready",
                "message_count": 0,
                "recent_failures": 0,
                "last_error": null,
                "lag": null,
                "details": {}
            },
            {
                "name": egress_name,
                "role": "egress",
                "transport": egress_transport,
                "connection_state": "ready",
                "message_count": 0,
                "recent_failures": 0,
                "last_error": null,
                "lag": null,
                "details": {}
            }
        ]
    })
}

fn spawn_runtime_reporting_keepalive(
    reporter: Option<&byteor_app_kit::agent::RuntimeReporter>,
    idle_snapshot: Option<serde_json::Value>,
) -> Option<(Arc<AtomicBool>, JoinHandle<()>)> {
    let mut reporter = reporter?.clone();
    let stop = Arc::new(AtomicBool::new(false));
    let stop_signal = Arc::clone(&stop);
    let handle = thread::spawn(move || {
        while !stop_signal.load(Ordering::Relaxed) {
            if let Err(error) = reporter.report_heartbeat_if_due() {
                eprintln!("agent heartbeat failed: {error}");
            }
            if let Some(snapshot) = idle_snapshot.as_ref() {
                if let Err(error) = reporter.report_snapshot_if_due("single_ring", || Ok(snapshot.clone())) {
                    eprintln!("agent snapshot failed: {error}");
                }
            }
            thread::sleep(Duration::from_millis(250));
        }
    });
    Some((stop, handle))
}

fn stop_runtime_reporting_keepalive(
    keepalive: Option<(Arc<AtomicBool>, JoinHandle<()>)>,
) {
    let Some((stop, handle)) = keepalive else {
        return;
    };
    stop.store(true, Ordering::Relaxed);
    let _ = handle.join();
}

fn main() {
    // Minimal enterprise app scaffolding.
    // In v1 we delegate operator tooling commands to `byteor-runtime` library helpers.

    let mut args = std::env::args().skip(1);
    let cmd = args.next().unwrap_or_else(|| "help".to_string());

    match cmd.as_str() {
        "help" | "-h" | "--help" => {
            eprintln!(
                "byteor-edgeplane\n\nUSAGE:\n  byteor-edgeplane validate --spec=/path\n  byteor-edgeplane describe --spec=/path\n  byteor-edgeplane dot --spec=/path\n  byteor-edgeplane run --spec=/path [--profile=default|low-latency|isolated-core] [--config=/path] [--lane-path=/path] [--shm-parent=/path] [--mlockall=on|off] [--wait=spin|backoff] [--pin=none|balanced|physical] [--sched=other|fifo|rr] [--rt-prio=N] [--dry-run] [--env=dev|staging|prod] [--approval=<credential>] [--approval-key-set=/path] [--adapter-max-messages=N]  # long-running (Ctrl-C to stop unless bounded)\n  byteor-edgeplane run --sp --spec=/path [--profile=default|low-latency|isolated-core] [--config=/path] [--lane-path=/path] [--shm-parent=/path] [--mlockall=on|off] [--wait=spin|backoff] [--pin=none|balanced|physical] [--sched=other|fifo|rr] [--rt-prio=N] [--input-hex=..|--input-ascii=..] [--dry-run] [--env=dev|staging|prod] [--approval=<credential>] [--approval-key-set=/path]  # one-shot SingleRing or long-running LaneGraph\n  byteor-edgeplane doctor [--profile=default|low-latency|isolated-core] [--mlockall=on|off] [--shm-parent=/path]\n  byteor-edgeplane snapshot --ring-path=/path [--active-gating=N]\n  byteor-edgeplane incident-bundle --out=/path --spec=/path [--config=/path] [--ring-path=/path]\n\nNOTES:\n  - ResolverKey stages supported:\n    - http_post:<url>\n    - exec:<program>|<arg>|...\n"
            );
            std::process::exit(2);
        }
        "validate" => {
            let mut spec: Option<PathBuf> = None;
            for a in args {
                if let Some(v) = a.strip_prefix("--spec=") {
                    spec = Some(PathBuf::from(v));
                } else {
                    eprintln!("unknown arg: {a}");
                    std::process::exit(2);
                }
            }

            let Some(spec) = spec else {
                eprintln!("missing --spec");
                std::process::exit(2);
            };

            match byteor_runtime::validate_spec_kv_v1(&spec) {
                Ok(()) => {
                    println!("{}", serde_json::json!({"ok": true}));
                    std::process::exit(0);
                }
                Err(e) => {
                    eprintln!("validate failed: {e}");
                    println!("{}", serde_json::json!({"ok": false, "error": e}));
                    std::process::exit(1);
                }
            }
        }
        "describe" => {
            let mut spec: Option<PathBuf> = None;
            for a in args {
                if let Some(v) = a.strip_prefix("--spec=") {
                    spec = Some(PathBuf::from(v));
                } else {
                    eprintln!("unknown arg: {a}");
                    std::process::exit(2);
                }
            }

            let Some(spec) = spec else {
                eprintln!("missing --spec");
                std::process::exit(2);
            };

            match byteor_runtime::describe_spec_kv_v1(&spec) {
                Ok(s) => {
                    print!("{s}");
                    std::process::exit(0);
                }
                Err(e) => {
                    eprintln!("describe failed: {e}");
                    std::process::exit(1);
                }
            }
        }
        "dot" => {
            let mut spec: Option<PathBuf> = None;
            for a in args {
                if let Some(v) = a.strip_prefix("--spec=") {
                    spec = Some(PathBuf::from(v));
                } else {
                    eprintln!("unknown arg: {a}");
                    std::process::exit(2);
                }
            }

            let Some(spec) = spec else {
                eprintln!("missing --spec");
                std::process::exit(2);
            };

            match byteor_runtime::dot_spec_kv_v1(&spec) {
                Ok(s) => {
                    print!("{s}");
                    std::process::exit(0);
                }
                Err(e) => {
                    eprintln!("dot failed: {e}");
                    std::process::exit(1);
                }
            }
        }
        "run" => {
            let mut sp = false;
            let mut spec: Option<PathBuf> = None;
            let mut lane_path: Option<PathBuf> = None;
            let mut rt_prio: Option<u8> = None;
            let mut input_hex: Option<String> = None;
            let mut input_ascii: Option<String> = None;
            let mut dry_run = false;
            let mut env = byteor_core::config::Environment::Dev;
            let mut approval: Option<String> = None;
            let mut approval_key_sets: Vec<PathBuf> = Vec::new();
            let mut config_path: Option<PathBuf> = None;
            let mut adapter_max_messages: Option<u64> = None;
            let mut tuning = byteor_runtime::TuningCliState::new(byteor_core::paths::shm_parent_from_env());

            for a in args {
                if a == "--sp" {
                    sp = true;
                } else if a == "--dry-run" {
                    dry_run = true;
                } else if let Some(v) = a.strip_prefix("--dry-run=") {
                    dry_run = matches!(v, "on" | "1" | "true" | "yes");
                } else if let Some(v) = a.strip_prefix("--spec=") {
                    spec = Some(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--lane-path=") {
                    lane_path = Some(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--profile=") {
                    let profile = byteor_runtime::TuningProfile::parse(v).unwrap_or_else(|| {
                        eprintln!(
                            "unknown --profile: {v} (expected default|low-latency|isolated-core)"
                        );
                        std::process::exit(2);
                    });
                    tuning.set_profile(profile);
                } else if let Some(v) = a.strip_prefix("--shm-parent=") {
                    tuning.set_shm_parent(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--mlockall=") {
                    let preset = match v {
                        "on" | "1" | "true" | "yes" => byteor_runtime::MlockallPreset::On,
                        "off" | "0" | "false" | "no" | "none" => {
                            byteor_runtime::MlockallPreset::None
                        }
                        _ => {
                            eprintln!("unknown --mlockall: {v} (expected on|off)");
                            std::process::exit(2);
                        }
                    };
                    tuning.set_mlockall(preset);
                } else if let Some(v) = a.strip_prefix("--sched=") {
                    let parsed_sched = match byteor_runtime::SchedPreset::parse_kind(v) {
                        Some(x) => x,
                        None => {
                            eprintln!("unknown --sched: {v} (expected other|fifo|rr)");
                            std::process::exit(2);
                        }
                    };
                    tuning.set_sched(parsed_sched);
                } else if let Some(v) = a.strip_prefix("--rt-prio=") {
                    rt_prio = Some(v.parse().unwrap_or_else(|_| {
                        eprintln!("invalid --rt-prio: {v}");
                        std::process::exit(2);
                    }));
                } else if let Some(v) = a.strip_prefix("--env=") {
                    env = match byteor_core::config::Environment::parse(v) {
                        Some(x) => x,
                        None => {
                            eprintln!("unknown --env: {v} (expected dev|staging|prod)");
                            std::process::exit(2);
                        }
                    };
                } else if let Some(v) = a.strip_prefix("--approval=") {
                    approval = Some(v.to_string());
                } else if let Some(v) = a.strip_prefix("--approval-key-set=") {
                    approval_key_sets.push(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--config=") {
                    config_path = Some(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--adapter-max-messages=") {
                    let parsed = v.parse().unwrap_or_else(|_| {
                        eprintln!("invalid --adapter-max-messages: {v}");
                        std::process::exit(2);
                    });
                    if parsed == 0 {
                        eprintln!("invalid --adapter-max-messages: {v} (expected > 0)");
                        std::process::exit(2);
                    }
                    adapter_max_messages = Some(parsed);
                } else if let Some(v) = a.strip_prefix("--wait=") {
                    let parsed_wait = byteor_runtime::parse_wait_preset(v).unwrap_or_else(|| {
                        eprintln!("unknown --wait preset: {v}");
                        std::process::exit(2);
                    });
                    tuning.set_wait(parsed_wait);
                } else if let Some(v) = a.strip_prefix("--pin=") {
                    let parsed_pinning = match byteor_runtime::PinningPreset::parse(v) {
                        Some(p) => p,
                        None => {
                            eprintln!(
                                "unknown --pin preset: {v} (expected none|balanced|physical)"
                            );
                            std::process::exit(2);
                        }
                    };
                    tuning.set_pinning(parsed_pinning);
                } else if let Some(v) = a.strip_prefix("--input-hex=") {
                    input_hex = Some(v.to_string());
                } else if let Some(v) = a.strip_prefix("--input-ascii=") {
                    input_ascii = Some(v.to_string());
                } else {
                    eprintln!("unknown arg: {a}");
                    std::process::exit(2);
                }
            }
            let Some(spec) = spec else {
                eprintln!("missing --spec");
                std::process::exit(2);
            };

            let mut resolved_tuning = tuning.resolve();
            if let Some(p) = rt_prio {
                if resolved_tuning.sched == byteor_runtime::SchedPreset::Other {
                    eprintln!("--rt-prio requires --sched=fifo|rr");
                    std::process::exit(2);
                }
                if !(1..=99).contains(&p) {
                    eprintln!("invalid --rt-prio: {p} (expected 1..=99)");
                    std::process::exit(2);
                }
                resolved_tuning.sched = resolved_tuning.sched.with_rt_prio(p);
            }
            let profile = resolved_tuning.profile;
            let wait = resolved_tuning.wait;
            let pinning = resolved_tuning.pinning;
            let mlockall = resolved_tuning.mlockall;
            let sched = resolved_tuning.sched;
            let shm_parent = resolved_tuning.shm_parent.clone();
            let tuning_report = byteor_runtime::effective_tuning_report(profile, &resolved_tuning);

            let lane_path = byteor_core::paths::default_lane_path_for_run(
                byteor_core::Product::Edgeplane,
                lane_path,
                &shm_parent,
            );

            if dry_run {
                match byteor_runtime::read_spec_kv_v1(&spec) {
                    Ok(spec_v1) => {
                        let stages = spec_v1.single_ring().map(|r| r.stages.len()).unwrap_or(0);
                        let resolved_config_path = config_path
                            .clone()
                            .or_else(|| byteor_runtime::default_bundle_config_path(&spec));
                        println!(
                            "{}",
                            serde_json::json!({
                                "ok": true,
                                "dry_run": true,
                                "model": format!("{:?}", spec_v1.model()).to_lowercase(),
                                "stages": stages,
                                "lane_path": lane_path.display().to_string(),
                                "config_path": resolved_config_path
                                    .as_ref()
                                    .map(|path| path.display().to_string()),
                            })
                        );
                        std::process::exit(0);
                    }
                    Err(e) => {
                        eprintln!("dry-run failed: {e}");
                        println!("{}", serde_json::json!({"ok": false, "error": e}));
                        std::process::exit(1);
                    }
                }
            }

            if let Err(e) = byteor_runtime::apply_mlockall_preset(mlockall) {
                eprintln!(
                    "{}",
                    byteor_runtime::tuning_host_readiness_error(format!(
                        "mlockall apply failed: preset={} err={e}",
                        mlockall.as_str()
                    ))
                );
                std::process::exit(1);
            }

            if let Err(e) = byteor_runtime::apply_sched_preset(sched) {
                eprintln!(
                    "{}",
                    byteor_runtime::tuning_host_readiness_error(format!(
                        "sched apply failed: sched={} prio={:?} err={e}",
                        sched.kind_str(),
                        sched.rt_prio()
                    ))
                );
                std::process::exit(1);
            }

            let canonical_spec_kv = match byteor_runtime::canonical_encode_spec_kv_v1(&spec) {
                Ok(spec_kv) => spec_kv,
                Err(e) => {
                    eprintln!("canonical spec failed: {e}");
                    println!("{}", serde_json::json!({"ok": false, "error": e}));
                    std::process::exit(1);
                }
            };

            if approval.is_none() {
                approval =
                    match byteor_app_kit::approval::load_approval_credential_from_bundle(&spec) {
                        Ok(credential) => credential,
                        Err(e) => {
                            eprintln!("approval credential load failed: {e}");
                            println!("{}", serde_json::json!({"ok": false, "error": e}));
                            std::process::exit(1);
                        }
                    };
            }

            if approval_key_sets.is_empty() {
                approval_key_sets =
                    byteor_app_kit::approval::discover_trusted_approval_key_paths(&spec);
            }

            let approval_refresh_bootstrap =
                match byteor_app_kit::approval::approval_refresh_bootstrap_from_env() {
                    Ok(bootstrap) => bootstrap,
                    Err(e) => {
                        eprintln!("approval key refresh bootstrap failed: {e}");
                        println!("{}", serde_json::json!({"ok": false, "error": e}));
                        std::process::exit(1);
                    }
                };

            let trusted_approval_cache =
                match byteor_app_kit::approval::load_runtime_trusted_approval_key_cache(
                    &spec,
                    &approval_key_sets,
                    approval_refresh_bootstrap.as_ref(),
                ) {
                    Ok(cache) => cache,
                    Err(e) => {
                        eprintln!("approval key set load failed: {e}");
                        println!("{}", serde_json::json!({"ok": false, "error": e}));
                        std::process::exit(1);
                    }
                };

            let approval_resolution = match byteor_app_kit::approval::resolve_runtime_approval(
                &canonical_spec_kv,
                env,
                approval.as_deref(),
                &trusted_approval_cache.keys,
            ) {
                Ok(resolution) => resolution,
                Err(byteor_app_kit::approval::ApprovalVerificationError::UnknownKeyId(_))
                    if approval_refresh_bootstrap.is_some() =>
                {
                    let refreshed_cache =
                        match byteor_app_kit::approval::refresh_runtime_trusted_approval_key_cache(
                            &spec,
                            &approval_key_sets,
                            approval_refresh_bootstrap
                                .as_ref()
                                .expect("refresh bootstrap present"),
                        ) {
                            Ok(cache) => cache,
                            Err(refresh_error) => {
                                let message = format!(
                                    "approval verification failed: unknown approval signing key and refresh failed: {refresh_error}"
                                );
                                eprintln!("{message}");
                                println!("{}", serde_json::json!({"ok": false, "error": message}));
                                std::process::exit(1);
                            }
                        };

                    match byteor_app_kit::approval::resolve_runtime_approval(
                        &canonical_spec_kv,
                        env,
                        approval.as_deref(),
                        &refreshed_cache.keys,
                    ) {
                        Ok(resolution) => resolution,
                        Err(e) => {
                            let message = format!("approval verification failed: {e}");
                            eprintln!("{message}");
                            println!("{}", serde_json::json!({"ok": false, "error": message}));
                            std::process::exit(1);
                        }
                    }
                }
                Err(e) => {
                    let message = format!("approval verification failed: {e}");
                    eprintln!("{message}");
                    println!("{}", serde_json::json!({"ok": false, "error": message}));
                    std::process::exit(1);
                }
            };

            let reporting_config = match byteor_app_kit::agent::reporting_config_from_bootstrap(
                approval_refresh_bootstrap.as_ref(),
            ) {
                Ok(config) => config,
                Err(e) => {
                    eprintln!("agent reporting bootstrap failed: {e}");
                    println!("{}", serde_json::json!({"ok": false, "error": e}));
                    std::process::exit(1);
                }
            };

            let approval_trust = match byteor_app_kit::agent::approval_trust_status(
                &trusted_approval_cache,
                approval.as_deref(),
            ) {
                Ok(status) => Some(status),
                Err(e) => {
                    eprintln!("agent approval trust export failed: {e}");
                    println!("{}", serde_json::json!({"ok": false, "error": e}));
                    std::process::exit(1);
                }
            };

            let mut stage_catalog = byteor_runtime::default_stage_catalog_entries();
            stage_catalog.extend(byteor_app_kit::actions::action_stage_catalog_entries());
            let capability_document =
                byteor_app_kit::capabilities::runtime_capability_document(
                    "byteor-edgeplane",
                    stage_catalog,
                );

            let mut runtime_reporter = reporting_config.map(|config| {
                byteor_app_kit::agent::RuntimeReporter::new(
                    config,
                    env!("CARGO_PKG_VERSION").to_string(),
                    approval_resolution.spec_hash.clone(),
                    capability_document,
                    approval_trust.clone(),
                )
            });

            // Minimal Edgeplane v1 stage resolver: action stages (exec/http_post). Built-in
            // `StageOpV1` stages (e.g. Identity/AddU8) do not require resolver wiring.
            let resolver = byteor_app_kit::actions::build_action_stages_default_replay(
                env,
                approval_resolution.approval_token_present,
                false, // is_replay
                false, // dry_run (side effects)
            );

            let spec_v1 = match byteor_runtime::read_spec_kv_v1(&spec) {
                Ok(spec_v1) => spec_v1,
                Err(e) => {
                    eprintln!("read spec failed: {e}");
                    println!("{}", serde_json::json!({"ok": false, "error": e}));
                    std::process::exit(1);
                }
            };

            if spec_v1.single_ring().is_some()
                && !sp
                && input_hex.is_none()
                && input_ascii.is_none()
            {
                let bundle_bindings = match byteor_runtime::load_single_ring_bundle_adapter_bindings(
                    &spec,
                    config_path.as_deref(),
                ) {
                    Ok(bindings) => bindings,
                    Err(e) => {
                        eprintln!("adapter bundle load failed: {e}");
                        println!("{}", serde_json::json!({"ok": false, "error": e}));
                        std::process::exit(1);
                    }
                };

                if let Some(bindings) = bundle_bindings {
                    let ingress_label = bindings.ingress.label();
                    let egress_label = bindings.egress.label();
                    let mut ingress = match byteor_runtime::open_ingress_endpoint(&bindings.ingress)
                    {
                        Ok(ingress) => ingress,
                        Err(e) => {
                            eprintln!("open ingress failed: {e}");
                            println!("{}", serde_json::json!({"ok": false, "error": e}));
                            std::process::exit(1);
                        }
                    };
                    let mut egress = match byteor_runtime::open_egress_endpoint(&bindings.egress) {
                        Ok(egress) => egress,
                        Err(e) => {
                            eprintln!("open egress failed: {e}");
                            println!("{}", serde_json::json!({"ok": false, "error": e}));
                            std::process::exit(1);
                        }
                    };

                    println!(
                        "{}",
                        serde_json::json!({
                            "ok": true,
                            "running": true,
                            "model": "single_ring",
                            "mode": "adapter_loop",
                            "config_path": bindings.config_path.display().to_string(),
                            "ingress_endpoint": bindings.ingress_name,
                            "egress_endpoint": bindings.egress_name,
                            "ingress_adapter": bindings.ingress_adapter,
                            "egress_adapter": bindings.egress_adapter,
                            "ingress": ingress_label,
                            "egress": egress_label,
                            "tuning": tuning_report.clone(),
                        })
                    );

                    if let Some(reporter) = runtime_reporter.as_ref() {
                        if let Err(e) = reporter.report_heartbeat_now() {
                            eprintln!("agent heartbeat failed: {e}");
                        }
                    }

                    let reporting_keepalive = spawn_runtime_reporting_keepalive(
                        runtime_reporter.as_ref(),
                        Some(idle_adapter_snapshot_payload(
                            &bindings.ingress_name,
                            &bindings.ingress_adapter,
                            &bindings.egress_name,
                            &bindings.egress_adapter,
                        )),
                    );

                    match byteor_adapters::run_single_ring_adapter_loop_with_options_and_observer(
                        &spec_v1,
                        &resolver,
                        &mut ingress,
                        &mut egress,
                        byteor_adapters::AdapterLoopOptions {
                            max_ingress_messages: adapter_max_messages,
                        },
                        |stats| {
                            if let Some(reporter) = runtime_reporter.as_mut() {
                                if let Err(e) = reporter.report_snapshot_if_due("single_ring", || {
                                    Ok(adapter_snapshot_payload(stats, None))
                                }) {
                                    eprintln!("agent snapshot failed: {e}");
                                }
                            }
                        },
                    ) {
                        Ok(stats) => {
                            stop_runtime_reporting_keepalive(reporting_keepalive);
                            report_adapter_snapshot(runtime_reporter.as_ref(), &stats, None);
                            println!(
                                "{}",
                                serde_json::json!({
                                    "ok": true,
                                    "stopped": true,
                                    "model": "single_ring",
                                    "mode": "adapter_loop",
                                    "ingress_messages": stats.ingress_messages,
                                    "egress_messages": stats.egress_messages,
                                })
                            );
                            std::process::exit(0);
                        }
                        Err(e) => {
                            stop_runtime_reporting_keepalive(reporting_keepalive);
                            report_adapter_snapshot(
                                runtime_reporter.as_ref(),
                                &e.stats,
                                Some(e.to_string()),
                            );
                            eprintln!("run failed: {e}");
                            println!(
                                "{}",
                                serde_json::json!({
                                    "ok": false,
                                    "error": e.to_string(),
                                    "model": "single_ring",
                                    "mode": "adapter_loop",
                                    "ingress_messages": e.stats.ingress_messages,
                                    "egress_messages": e.stats.egress_messages,
                                })
                            );
                            std::process::exit(1);
                        }
                    }
                }
            }

            if spec_v1.single_ring().is_none() {
                if input_hex.is_some() || input_ascii.is_some() {
                    eprintln!("--input-* is not supported for lane_graph");
                    std::process::exit(2);
                }

                let stop = Arc::new(AtomicBool::new(false));
                {
                    let stop2 = stop.clone();
                    ctrlc::set_handler(move || {
                        stop2.store(true, Ordering::Relaxed);
                    })
                    .unwrap_or_else(|e| {
                        eprintln!("failed to install ctrlc handler: {e}");
                        std::process::exit(2);
                    });
                }

                let thread_init = byteor_runtime::thread_init_hook_for_tuning(pinning, sched)
                    .unwrap_or_else(|e| {
                        eprintln!(
                            "{}",
                            byteor_runtime::tuning_host_readiness_error(format!(
                                "tuning init failed: {e}"
                            ))
                        );
                        std::process::exit(2);
                    });

                let engine = byteor_engine::Engine::new(byteor_engine::EngineConfig {
                    stage_failure: byteor_engine::StageFailurePolicy::StopPipeline,
                    wait,
                    thread_init,
                });

                println!(
                    "{}",
                    serde_json::json!({
                        "ok": true,
                        "running": true,
                        "model": "lane_graph",
                        "mode": "sp",
                        "tuning": tuning_report,
                    })
                );

                let rt = engine
                    .spawn_lane_graph_kv_v1_runtime(&spec, &resolver)
                    .unwrap_or_else(|e| {
                        eprintln!("run failed: {e}");
                        println!(
                            "{}",
                            serde_json::json!({"ok": false, "error": e.to_string()})
                        );
                        std::process::exit(1);
                    });

                let lane_root = byteor_runtime::default_lane_graph_shm_dir(&spec);

                while !stop.load(Ordering::Relaxed) {
                    if let Some(reporter) = runtime_reporter.as_mut() {
                        if let Err(e) = reporter.report_heartbeat_if_due() {
                            eprintln!("agent heartbeat failed: {e}");
                        }
                        if let Err(e) = reporter.report_snapshot_if_due("lane_graph", || {
                            let role_activity = rt.role_activity_snapshot();
                            byteor_runtime::snapshot_lane_graph_json(
                                &spec,
                                Some(lane_root.as_path()),
                                Some(role_activity.as_slice()),
                            )
                        }) {
                            eprintln!("agent snapshot failed: {e}");
                        }
                    }
                    std::thread::sleep(std::time::Duration::from_millis(50));
                }

                if let Some(reporter) = runtime_reporter.as_ref() {
                    if let Err(e) = reporter.report_heartbeat_now() {
                        eprintln!("agent heartbeat failed: {e}");
                    }
                    if let Err(e) = reporter.report_snapshot_now("lane_graph", || {
                        let role_activity = rt.role_activity_snapshot();
                        byteor_runtime::snapshot_lane_graph_json(
                            &spec,
                            Some(lane_root.as_path()),
                            Some(role_activity.as_slice()),
                        )
                    }) {
                        eprintln!("agent snapshot failed: {e}");
                    }
                }

                if let Err(e) = rt.stop_and_join() {
                    eprintln!("stop/join failed: {e}");
                    println!(
                        "{}",
                        serde_json::json!({"ok": false, "error": e.to_string()})
                    );
                    std::process::exit(1);
                }

                println!("{}", serde_json::json!({"ok": true, "stopped": true}));
                std::process::exit(0);
            }

            if !sp {
                if input_hex.is_some() || input_ascii.is_some() {
                    eprintln!("--input-* is only supported for --sp");
                    std::process::exit(2);
                }

                let stop = Arc::new(AtomicBool::new(false));
                {
                    let stop2 = stop.clone();
                    ctrlc::set_handler(move || {
                        stop2.store(true, Ordering::Relaxed);
                    })
                    .unwrap_or_else(|e| {
                        eprintln!("failed to install ctrlc handler: {e}");
                        std::process::exit(2);
                    });
                }

                println!(
                    "{}",
                    serde_json::json!({
                        "ok": true,
                        "running": true,
                        "model": "single_ring",
                        "lane_path": lane_path.display().to_string(),
                    })
                );

                match byteor_runtime::run_kv_v1_single_ring_supervised_until_stop_with_resolver_and_tuning(
                    &spec,
                    lane_path,
                    wait,
                    stop,
                    &resolver,
                    pinning,
                    sched,
                ) {
                    Ok(()) => {
                        println!("{}", serde_json::json!({"ok": true, "stopped": true}));
                        std::process::exit(0);
                    }
                    Err(e) => {
                        eprintln!("run failed: {e}");
                        println!("{}", serde_json::json!({"ok": false, "error": e}));
                        std::process::exit(1);
                    }
                }
            }

            let input =
                match byteor_runtime::parse_run_input(input_hex.as_deref(), input_ascii.as_deref())
                {
                    Ok(v) => v,
                    Err(e) => {
                        eprintln!("invalid input: {e}");
                        std::process::exit(2);
                    }
                };

            match byteor_runtime::run_sp_kv_v1_single_ring_with_resolver_and_tuning(
                &spec, lane_path, input, wait, &resolver, pinning, sched,
            ) {
                Ok(v) => {
                    println!("{}", serde_json::to_string_pretty(&v).unwrap());
                    std::process::exit(0);
                }
                Err(e) => {
                    eprintln!("run failed: {e}");
                    println!("{}", serde_json::json!({"ok": false, "error": e}));
                    std::process::exit(1);
                }
            }
        }
        "doctor" => {
            let mut tuning = byteor_runtime::TuningCliState::new(byteor_core::paths::shm_parent_from_env());

            for a in args {
                if let Some(v) = a.strip_prefix("--profile=") {
                    let profile = byteor_runtime::TuningProfile::parse(v).unwrap_or_else(|| {
                        eprintln!(
                            "unknown --profile: {v} (expected default|low-latency|isolated-core)"
                        );
                        std::process::exit(2);
                    });
                    tuning.set_profile(profile);
                } else if let Some(v) = a.strip_prefix("--mlockall=") {
                    let mlockall = match v {
                        "on" | "1" | "true" | "yes" => byteor_runtime::MlockallPreset::On,
                        "off" | "0" | "false" | "no" | "none" => byteor_runtime::MlockallPreset::None,
                        _ => {
                            eprintln!("unknown --mlockall: {v} (expected on|off)");
                            std::process::exit(2);
                        }
                    };
                    tuning.set_mlockall(mlockall);
                } else if let Some(v) = a.strip_prefix("--shm-parent=") {
                    tuning.set_shm_parent(PathBuf::from(v));
                } else {
                    eprintln!("unknown arg: {a}");
                    std::process::exit(2);
                }
            }

            let resolved = tuning.resolve();
            let report = byteor_runtime::doctor_with_tuning(&resolved);
            byteor_runtime::eprint_human(&report.checks);
            println!("{}", serde_json::to_string_pretty(&report).unwrap());
            std::process::exit(if report.ok { 0 } else { 1 });
        }
        "snapshot" => {
            let mut ring_path: Option<PathBuf> = None;
            let mut active_gating: usize = 4;

            for a in args {
                if let Some(v) = a.strip_prefix("--ring-path=") {
                    ring_path = Some(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--active-gating=") {
                    active_gating = v.parse().unwrap_or(4);
                } else {
                    eprintln!("unknown arg: {a}");
                    std::process::exit(2);
                }
            }

            let Some(ring_path) = ring_path else {
                eprintln!("missing --ring-path");
                std::process::exit(2);
            };

            match byteor_runtime::snapshot_single_ring_json(ring_path, active_gating) {
                Ok(v) => {
                    println!("{}", serde_json::to_string_pretty(&v).unwrap());
                    std::process::exit(0);
                }
                Err(e) => {
                    eprintln!("snapshot failed: {e}");
                    std::process::exit(1);
                }
            }
        }
        "incident-bundle" => {
            let mut out: Option<PathBuf> = None;
            let mut spec: Option<PathBuf> = None;
            let mut config: Option<PathBuf> = None;
            let mut ring_path: Option<PathBuf> = None;

            for a in args {
                if let Some(v) = a.strip_prefix("--out=") {
                    out = Some(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--spec=") {
                    spec = Some(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--config=") {
                    config = Some(PathBuf::from(v));
                } else if let Some(v) = a.strip_prefix("--ring-path=") {
                    ring_path = Some(PathBuf::from(v));
                } else {
                    eprintln!("unknown arg: {a}");
                    std::process::exit(2);
                }
            }

            let Some(out) = out else {
                eprintln!("missing --out");
                std::process::exit(2);
            };
            let Some(spec) = spec else {
                eprintln!("missing --spec");
                std::process::exit(2);
            };

            let res = byteor_runtime::incident_bundle(
                &out,
                &spec,
                config.as_deref(),
                ring_path.as_deref(),
            );

            match res {
                Ok(()) => {
                    println!(
                        "{}",
                        serde_json::json!({"ok": true, "out": out.display().to_string() })
                    );
                    std::process::exit(0);
                }
                Err(e) => {
                    eprintln!("incident-bundle failed: {e}");
                    println!("{}", serde_json::json!({"ok": false, "error": e }));
                    std::process::exit(1);
                }
            }
        }
        other => {
            eprintln!("unknown command: {other}");
            std::process::exit(2);
        }
    }
}