feat(cli): warn about duplicate agent executables

Author: ericevans-nv

crates/cli/src/commands/diagnostics.rs

@@ -4,15 +4,18 @@
 use std::path::PathBuf;
 use std::process::ExitCode;
 
-use clap::Args;
+use clap::{Args, Subcommand};
 use serde_json::{Value, json};
 
 use super::install::InstallTarget;
 use super::root::AgentArg;
 use crate::error::CliError;
 
 #[derive(Debug, Clone, Args)]
+#[command(args_conflicts_with_subcommands = true)]
 pub(crate) struct DoctorCommand {
+    #[command(subcommand)]
+    pub(crate) command: Option<DoctorSubcommand>,
     #[arg(value_enum, conflicts_with = "plugin")]
     pub(crate) agent: Option<AgentArg>,
     #[arg(long, value_enum)]
@@ -28,6 +31,27 @@ pub(crate) struct DoctorCommand {
     pub(crate) offline: bool,
 }
 
+#[derive(Debug, Clone, Subcommand)]
+pub(crate) enum DoctorSubcommand {
+    /// Inspect an agent invocation without launching it.
+    Invocation(InvocationDoctorCommand),
+}
+
+#[derive(Debug, Clone, Args)]
+pub(crate) struct InvocationDoctorCommand {
+    #[arg(long, value_enum)]
+    agent: AgentArg,
+    #[arg(long)]
+    shortcut: bool,
+    #[arg(
+        long,
+        help = "Display the complete invocation; arguments may contain sensitive data"
+    )]
+    show_full_command: bool,
+    #[arg(last = true, required = true)]
+    command: Vec<String>,
+}
+
 #[derive(Debug, Clone, Args)]
 pub(crate) struct AgentsCommand {
     #[arg(long)]
@@ -39,6 +63,9 @@ pub(super) async fn execute(
     server: &super::serve::ServerArgs,
     logging_fallback_error: Option<&CliError>,
 ) -> Result<ExitCode, CliError> {
+    if let Some(DoctorSubcommand::Invocation(invocation)) = command.command {
+        return execute_invocation_doctor(invocation);
+    }
     if let Some(plugin) = command.plugin {
         return execute_plugin_doctor(plugin, command.install_dir, command.json);
     }
@@ -53,6 +80,31 @@ pub(super) async fn execute(
     .await
 }
 
+fn execute_invocation_doctor(command: InvocationDoctorCommand) -> Result<ExitCode, CliError> {
+    let agent = command.agent.into();
+    let form = if command.shortcut {
+        crate::diagnostics::invocation::InvocationForm::Shortcut
+    } else {
+        crate::diagnostics::invocation::InvocationForm::Run
+    };
+    match crate::diagnostics::invocation::DuplicateAgentExecutable::detect(
+        agent,
+        &command.command,
+        form,
+    ) {
+        Some(diagnostic) => {
+            println!("{}", diagnostic.format_doctor(command.show_full_command));
+        }
+        None => {
+            println!(
+                "INVOCATION DIAGNOSTIC\ncode = none\nselected_agent = {}\nresult = no duplicate agent executable detected",
+                agent.as_arg()
+            );
+        }
+    }
+    Ok(ExitCode::SUCCESS)
+}
+
 fn execute_plugin_doctor(
     plugin: InstallTarget,
     install_dir: Option<PathBuf>,

crates/cli/src/commands/mod.rs

@@ -102,6 +102,10 @@ fn configure_logging(cli: &Cli) -> Result<LoggingSetup, error::CliError> {
     })
 }
 
+fn print_invocation_warning(warning: &str) {
+    eprintln!("{warning}");
+}
+
 async fn dispatch(bootstrap_shutdown_token: Option<String>) -> Result<ExitCode, error::CliError> {
     let cli = Cli::parse();
     let command_name = cli

crates/cli/src/commands/run.rs

@@ -60,6 +60,13 @@ pub(super) async fn execute(
     command: RunCommand,
     server: &ServerArgs,
 ) -> Result<ExitCode, CliError> {
+    if let Some(agent) = command.agent.map(Into::into) {
+        warn_for_possible_duplicate(
+            agent,
+            &command.command,
+            crate::diagnostics::invocation::InvocationForm::Run,
+        );
+    }
     let inherited = server.to_runtime();
     crate::process::launcher::run(command.into_runtime(), Some(&inherited)).await
 }
@@ -79,6 +86,11 @@ pub(super) async fn easy_path(
     command: EasyPathCommand,
     server: &ServerArgs,
 ) -> Result<ExitCode, CliError> {
+    warn_for_possible_duplicate(
+        agent,
+        &command.command,
+        crate::diagnostics::invocation::InvocationForm::Shortcut,
+    );
     let inherited = server.to_runtime();
     // An explicit config path is the user's contract. Without one, setup is required only when
     // none of the normal discovery layers exists. Keep this interactive decision in the command
@@ -102,3 +114,16 @@ pub(super) async fn easy_path(
     };
     crate::process::launcher::run(runtime, Some(&inherited)).await
 }
+
+fn warn_for_possible_duplicate(
+    agent: CodingAgent,
+    command: &[String],
+    form: crate::diagnostics::invocation::InvocationForm,
+) {
+    if let Some(diagnostic) =
+        crate::diagnostics::invocation::DuplicateAgentExecutable::detect(agent, command, form)
+    {
+        diagnostic.log();
+        super::print_invocation_warning(&diagnostic.format_warning());
+    }
+}

crates/cli/src/diagnostics/invocation.rs

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Advisory diagnostics for structurally suspicious agent invocations.
+
+use crate::agents::CodingAgent;
+
+pub(crate) const POSSIBLE_DUPLICATE_AGENT_EXECUTABLE: &str = "possible_duplicate_agent_executable";
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum InvocationForm {
+    Run,
+    Shortcut,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct DuplicateAgentExecutable {
+    agent: CodingAgent,
+    form: InvocationForm,
+    command: Vec<String>,
+}
+
+impl DuplicateAgentExecutable {
+    pub(crate) fn detect(
+        agent: CodingAgent,
+        command: &[String],
+        form: InvocationForm,
+    ) -> Option<Self> {
+        let executable = command.first()?;
+        (CodingAgent::infer(executable) == Some(agent)).then(|| Self {
+            agent,
+            form,
+            command: command.to_vec(),
+        })
+    }
+
+    pub(crate) fn log(&self) {
+        let agent = self.agent.as_arg();
+        log::warn!(
+            target: "nemo_relay.cli",
+            event = "agent_invocation_warning",
+            diagnostic_code = POSSIBLE_DUPLICATE_AGENT_EXECUTABLE,
+            agent = agent,
+            duplicate_executable = agent,
+            confidence = "high",
+            action = "continued",
+            command_modified = false,
+            arguments_redacted = true;
+            "Possible duplicate agent executable after `--`"
+        );
+    }
+
+    pub(crate) fn format_doctor(&self, show_full_command: bool) -> String {
+        let visibility = if show_full_command {
+            "full command; may contain sensitive data"
+        } else {
+            "arguments redacted"
+        };
+        format!(
+            "INVOCATION DIAGNOSTIC\n\
+             code = {POSSIBLE_DUPLICATE_AGENT_EXECUTABLE}\n\
+             confidence = high\n\
+             selected_agent = {}\n\
+             duplicate_executable = {}\n\
+             visibility = {visibility}\n\
+             observed = {}\n\
+             recommended = {}\n\
+             action = continue unchanged",
+            self.agent.as_arg(),
+            self.agent.as_arg(),
+            self.observed_command(show_full_command),
+            self.recommended_command(show_full_command),
+        )
+    }
+
+    pub(crate) fn format_warning(&self) -> String {
+        format!(
+            "WARNING: Possible duplicate agent executable after `--`.\n\
+               Diagnostic: {POSSIBLE_DUPLICATE_AGENT_EXECUTABLE}\n\
+               Duplicate executable: {}\n\
+               Observed: {}\n\
+               Recommended: {}\n\
+               Doctor (safe): {}\n\
+               Doctor (full): {}\n\
+               Relay will continue without modifying the command.",
+            self.agent.as_arg(),
+            self.observed_command(false),
+            self.recommended_command(false),
+            self.doctor_command(false),
+            self.doctor_command(true),
+        )
+    }
+
+    fn observed_command(&self, show_full_command: bool) -> String {
+        let mut command = self.relay_prefix();
+        command.push("--".into());
+        if show_full_command {
+            command.extend(self.command.iter().cloned());
+        } else {
+            command.push(self.agent.as_arg().into());
+            if self.command.len() > 1 {
+                command.push("<arguments redacted>".into());
+            }
+        }
+        render_command(&command)
+    }
+
+    fn recommended_command(&self, show_full_command: bool) -> String {
+        let mut command = self.relay_prefix();
+        command.push("--".into());
+        if show_full_command {
+            command.extend(self.command.iter().skip(1).cloned());
+        } else if self.command.len() > 1 {
+            command.push("<arguments redacted>".into());
+        }
+        render_command(&command)
+    }
+
+    fn doctor_command(&self, show_full_command: bool) -> String {
+        let mut command = vec![
+            "nemo-relay".into(),
+            "doctor".into(),
+            "invocation".into(),
+            "--agent".into(),
+            self.agent.as_arg().into(),
+        ];
+        if self.form == InvocationForm::Shortcut {
+            command.push("--shortcut".into());
+        }
+        if show_full_command {
+            command.push("--show-full-command".into());
+        }
+        command.push("--".into());
+        command.push(self.agent.as_arg().into());
+        if show_full_command && self.command.len() > 1 {
+            command.push("<original arguments>".into());
+        }
+        render_command(&command)
+    }
+
+    fn relay_prefix(&self) -> Vec<String> {
+        match self.form {
+            InvocationForm::Run => vec![
+                "nemo-relay".into(),
+                "run".into(),
+                "--agent".into(),
+                self.agent.as_arg().into(),
+            ],
+            InvocationForm::Shortcut => {
+                vec!["nemo-relay".into(), self.agent.as_arg().into()]
+            }
+        }
+    }
+}
+
+fn render_command(command: &[String]) -> String {
+    command
+        .iter()
+        .map(|argument| crate::process::shell_quote_arg_for_platform(argument, cfg!(windows)))
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+#[cfg(test)]
+#[path = "../../tests/coverage/shared/invocation_diagnostic_tests.rs"]
+mod tests;

crates/cli/src/diagnostics/mod.rs

@@ -10,6 +10,7 @@
 //! - `format_human(&report)` / `format_json(&report)` render the report.
 
 mod environment;
+pub(crate) mod invocation;
 mod model;
 mod probes;
 mod render;